specdojo 0.8.0 → 0.9.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 (292) hide show
  1. package/.github/agents/specdojo-orchestrator.md +4 -1
  2. package/CHANGELOG.md +77 -0
  3. package/dist/catalog/catalog.js +16 -14
  4. package/dist/commands/agent.js +5 -3
  5. package/dist/commands/build.js +69 -10
  6. package/dist/commands/git.js +206 -0
  7. package/dist/commands/init.js +4 -2
  8. package/dist/commands/orchestrator.js +5 -77
  9. package/dist/commands/where.js +25 -0
  10. package/dist/dashboard/dashboard.js +5 -3
  11. package/dist/dashboard/routines.js +4 -7
  12. package/dist/dashboard/shared.js +2 -2
  13. package/dist/dashboard/timeline.js +14 -14
  14. package/dist/deliverable/trash.js +2 -1
  15. package/dist/docs/index-command.js +2 -2
  16. package/dist/docs/yaml-business-tables.js +243 -0
  17. package/dist/docs/yaml-interface-tables.js +106 -0
  18. package/dist/docs/yaml-pages-command.js +5 -3
  19. package/dist/docs/yaml-pages.js +146 -3
  20. package/dist/docs/yaml-table-shared.js +70 -0
  21. package/dist/docs/yaml-tables.js +39 -0
  22. package/dist/exec/agent-config.js +9 -0
  23. package/dist/exec/agent-protected-config.js +2 -0
  24. package/dist/exec/commands.js +31 -18
  25. package/dist/exec/events.js +34 -14
  26. package/dist/exec/evidence.js +13 -3
  27. package/dist/exec/opencode-permissions.js +117 -0
  28. package/dist/exec/parent-validation.js +56 -3
  29. package/dist/exec/plans-core.js +21 -2
  30. package/dist/exec/plans-generation.js +6 -7
  31. package/dist/exec/post-integration.js +162 -0
  32. package/dist/exec/queue-command.js +166 -0
  33. package/dist/exec/queue.js +285 -0
  34. package/dist/exec/register-foreign-wait.js +82 -0
  35. package/dist/exec/repo-integration-sync.js +17 -5
  36. package/dist/exec/repo-trace.js +2 -1
  37. package/dist/exec/reporter.js +2 -2
  38. package/dist/exec/results.js +24 -4
  39. package/dist/exec/review-kata.js +4 -1
  40. package/dist/exec/run/agent-pipeline.js +3 -2
  41. package/dist/exec/run/agent.js +12 -6
  42. package/dist/exec/run/change-scope.js +365 -0
  43. package/dist/exec/run/deferred-cleanup.js +31 -0
  44. package/dist/exec/run/in-place.js +5 -2
  45. package/dist/exec/run/job-lock.js +66 -0
  46. package/dist/exec/run/job-sequence.js +137 -0
  47. package/dist/exec/run/job.js +56 -19
  48. package/dist/exec/run/lifecycle-commands.js +1 -1
  49. package/dist/exec/run/lock.js +22 -1
  50. package/dist/exec/run/register-command.js +8 -5
  51. package/dist/exec/run/register-mode.js +68 -8
  52. package/dist/exec/run/register-resume.js +68 -14
  53. package/dist/exec/run/register-state.js +13 -8
  54. package/dist/exec/run/register-worktree.js +140 -125
  55. package/dist/exec/run/schedule-mode.js +75 -14
  56. package/dist/exec/run/schedule-prepare.js +3 -0
  57. package/dist/exec/run/schedule-task.js +88 -38
  58. package/dist/exec/run/shared.js +5 -0
  59. package/dist/exec/schedule/schedule.js +116 -4
  60. package/dist/exec/shared.js +2 -2
  61. package/dist/exec/smoke.js +190 -0
  62. package/dist/exec/strategy.js +13 -3
  63. package/dist/exec/task-repos.js +19 -4
  64. package/dist/exec/task-view.js +6 -4
  65. package/dist/exec/trial-commands.js +5 -2
  66. package/dist/exec/trial-core.js +6 -1
  67. package/dist/exec/validation-metrics.js +181 -0
  68. package/dist/exec/worktree-cleanup-lock.js +26 -0
  69. package/dist/exec/worktree-command.js +12 -2
  70. package/dist/exec/worktree-ops-commit.js +2 -2
  71. package/dist/exec/worktree.js +13 -2
  72. package/dist/grade/command-apply.js +3 -3
  73. package/dist/grade/command-inspect.js +5 -3
  74. package/dist/grade/command-plan.js +1 -1
  75. package/dist/grade/command-run.js +5 -1
  76. package/dist/grade/run.js +64 -8
  77. package/dist/job/definition.js +84 -8
  78. package/dist/job/job.js +79 -23
  79. package/dist/register/authoring-sources.js +22 -16
  80. package/dist/register/maintenance-commands.js +2 -2
  81. package/dist/register/register.js +31 -7
  82. package/dist/register/renumber.js +1 -3
  83. package/dist/routine/definition.js +9 -0
  84. package/dist/routine/routine.js +137 -43
  85. package/dist/routine/status.js +62 -0
  86. package/dist/schedule/schedule.js +38 -39
  87. package/dist/shared/agent-types.js +5 -0
  88. package/dist/shared/cross-process-lock.js +9 -1
  89. package/dist/shared/dist-freshness.js +8 -2
  90. package/dist/shared/git-environment.js +2 -1
  91. package/dist/shared/git.js +44 -1
  92. package/dist/shared/lefthook-scaffold.js +3 -0
  93. package/dist/shared/local-config.js +244 -0
  94. package/dist/shared/specdojo-config.js +34 -20
  95. package/dist/shared/specdojo-gitignore.js +1 -0
  96. package/dist/shared/text.js +17 -1
  97. package/dist/shared/where-alias.js +13 -0
  98. package/dist/specdojo.js +4 -0
  99. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +2 -0
  100. package/docs/ja/specdojo/guides/exec-config-guide.md +23 -4
  101. package/docs/ja/specdojo/guides/exec-operation-guide.md +44 -1
  102. package/docs/ja/specdojo/guides/job-sequence-guide.md +77 -0
  103. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +1 -1
  104. package/docs/ja/specdojo/guides/quick-start-guide.md +3 -3
  105. package/docs/ja/specdojo/guides/register-operation-guide.md +1 -1
  106. package/docs/ja/specdojo/guides/routine-operation-guide.md +11 -6
  107. package/docs/ja/specdojo/guides/schedule-design-guide.md +20 -17
  108. package/docs/ja/specdojo/guides/waza-guide.md +12 -8
  109. package/docs/ja/specdojo/recipes/bac-recipe.md +66 -49
  110. package/docs/ja/specdojo/recipes/bes-recipe.md +90 -54
  111. package/docs/ja/specdojo/recipes/bps-recipe.md +88 -139
  112. package/docs/ja/specdojo/recipes/br-recipe.md +40 -47
  113. package/docs/ja/specdojo/recipes/cdfd-overview-recipe.md +97 -109
  114. package/docs/ja/specdojo/recipes/cdfd-recipe.md +85 -146
  115. package/docs/ja/specdojo/recipes/cdfd-uc-recipe.md +91 -110
  116. package/docs/ja/specdojo/recipes/cnd-recipe.md +79 -69
  117. package/docs/ja/specdojo/recipes/cpd-recipe.md +78 -64
  118. package/docs/ja/specdojo/recipes/cxd-recipe.md +92 -75
  119. package/docs/ja/specdojo/recipes/ifd-recipe.md +79 -68
  120. package/docs/ja/specdojo/recipes/ifx-cmd-recipe.md +78 -105
  121. package/docs/ja/specdojo/recipes/ifx-index-recipe.md +105 -71
  122. package/docs/ja/specdojo/recipes/pm-communication-plan-recipe.md +60 -49
  123. package/docs/ja/specdojo/recipes/pm-members-recipe.md +50 -51
  124. package/docs/ja/specdojo/recipes/pm-organization-recipe.md +59 -51
  125. package/docs/ja/specdojo/recipes/pm-plan-recipe.md +69 -56
  126. package/docs/ja/specdojo/recipes/pm-quality-management-plan-recipe.md +37 -56
  127. package/docs/ja/specdojo/recipes/pm-raci-recipe.md +39 -53
  128. package/docs/ja/specdojo/recipes/pm-roles-recipe.md +52 -79
  129. package/docs/ja/specdojo/recipes/prj-assumptions-constraints-dependencies-recipe.md +64 -93
  130. package/docs/ja/specdojo/recipes/prj-charter-recipe.md +71 -106
  131. package/docs/ja/specdojo/recipes/prj-comparison-of-alternatives-recipe.md +78 -157
  132. package/docs/ja/specdojo/recipes/prj-issues-and-approach-recipe.md +62 -111
  133. package/docs/ja/specdojo/recipes/prj-scope-recipe.md +67 -123
  134. package/docs/ja/specdojo/recipes/prj-stakeholder-register-recipe.md +60 -96
  135. package/docs/ja/specdojo/recipes/prj-success-criteria-and-acceptance-criteria-recipe.md +61 -105
  136. package/docs/ja/specdojo/recipes/stsd-recipe.md +79 -109
  137. package/docs/ja/specdojo/recipes/sysd-critical-flows-recipe.md +78 -55
  138. package/docs/ja/specdojo/recipes/sysd-cross-cutting-policy-recipe.md +82 -73
  139. package/docs/ja/specdojo/recipes/sysd-index-recipe.md +78 -59
  140. package/docs/ja/specdojo/recipes/tsd-recipe.md +149 -129
  141. package/docs/ja/specdojo/references/command-reference.md +258 -118
  142. package/docs/ja/specdojo/references/deliverables-reference.md +21 -12
  143. package/docs/ja/specdojo/references/specdojo-config-reference.md +47 -10
  144. package/docs/ja/specdojo/rulebooks/atc-index-rulebook.md +101 -257
  145. package/docs/ja/specdojo/rulebooks/atc-rulebook.md +102 -228
  146. package/docs/ja/specdojo/rulebooks/bac-rulebook.md +19 -28
  147. package/docs/ja/specdojo/rulebooks/bdd-rulebook.md +16 -67
  148. package/docs/ja/specdojo/rulebooks/bds-rulebook.md +30 -51
  149. package/docs/ja/specdojo/rulebooks/bes-index-rulebook.md +41 -61
  150. package/docs/ja/specdojo/rulebooks/bes-rulebook.md +22 -50
  151. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +24 -56
  152. package/docs/ja/specdojo/rulebooks/br-rulebook.md +13 -38
  153. package/docs/ja/specdojo/rulebooks/ccd-mermaid-rulebook.md +41 -76
  154. package/docs/ja/specdojo/rulebooks/cdfd-d2-rulebook.md +18 -93
  155. package/docs/ja/specdojo/rulebooks/cdfd-mermaid-rulebook.md +18 -52
  156. package/docs/ja/specdojo/rulebooks/cdfd-overview-rulebook.md +109 -147
  157. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +80 -108
  158. package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +21 -46
  159. package/docs/ja/specdojo/rulebooks/cdr-rulebook.md +144 -0
  160. package/docs/ja/specdojo/rulebooks/cdsd-rulebook.md +27 -48
  161. package/docs/ja/specdojo/rulebooks/cdt-rulebook.md +37 -50
  162. package/docs/ja/specdojo/rulebooks/clis-rulebook.md +52 -69
  163. package/docs/ja/specdojo/rulebooks/cnd-mermaid-rulebook.md +33 -86
  164. package/docs/ja/specdojo/rulebooks/cnd-rulebook.md +16 -32
  165. package/docs/ja/specdojo/rulebooks/cop-index-rulebook.md +45 -131
  166. package/docs/ja/specdojo/rulebooks/cop-rulebook.md +69 -275
  167. package/docs/ja/specdojo/rulebooks/cpd-mermaid-rulebook.md +20 -112
  168. package/docs/ja/specdojo/rulebooks/cpd-rulebook.md +23 -56
  169. package/docs/ja/specdojo/rulebooks/cxd-mermaid-rulebook.md +12 -145
  170. package/docs/ja/specdojo/rulebooks/cxd-rulebook.md +39 -47
  171. package/docs/ja/specdojo/rulebooks/dct-index-rulebook.md +37 -56
  172. package/docs/ja/specdojo/rulebooks/dct-rulebook.md +118 -175
  173. package/docs/ja/specdojo/rulebooks/dec-rulebook.md +5 -14
  174. package/docs/ja/specdojo/rulebooks/dmd-index-rulebook.md +22 -66
  175. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +36 -94
  176. package/docs/ja/specdojo/rulebooks/dss-rulebook.md +59 -81
  177. package/docs/ja/specdojo/rulebooks/etc-index-rulebook.md +31 -131
  178. package/docs/ja/specdojo/rulebooks/etc-rulebook.md +50 -104
  179. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +51 -61
  180. package/docs/ja/specdojo/rulebooks/ifd-mermaid-rulebook.md +38 -45
  181. package/docs/ja/specdojo/rulebooks/ifx-api-rulebook.md +14 -20
  182. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +26 -38
  183. package/docs/ja/specdojo/rulebooks/ifx-file-rulebook.md +26 -107
  184. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +42 -49
  185. package/docs/ja/specdojo/rulebooks/ifx-msg-rulebook.md +14 -22
  186. package/docs/ja/specdojo/rulebooks/imp-business-rulebook.md +21 -44
  187. package/docs/ja/specdojo/rulebooks/imp-data-rulebook.md +41 -64
  188. package/docs/ja/specdojo/rulebooks/imp-interface-rulebook.md +14 -38
  189. package/docs/ja/specdojo/rulebooks/imp-operations-rulebook.md +34 -61
  190. package/docs/ja/specdojo/rulebooks/imp-test-rulebook.md +27 -50
  191. package/docs/ja/specdojo/rulebooks/itc-index-rulebook.md +70 -199
  192. package/docs/ja/specdojo/rulebooks/itc-rulebook.md +65 -153
  193. package/docs/ja/specdojo/rulebooks/mip-index-rulebook.md +74 -150
  194. package/docs/ja/specdojo/rulebooks/mm-rulebook.md +11 -23
  195. package/docs/ja/specdojo/rulebooks/mtp-rulebook.md +99 -176
  196. package/docs/ja/specdojo/rulebooks/nfr-availability-rulebook.md +35 -61
  197. package/docs/ja/specdojo/rulebooks/nfr-index-rulebook.md +75 -117
  198. package/docs/ja/specdojo/rulebooks/nfr-integrity-rulebook.md +31 -60
  199. package/docs/ja/specdojo/rulebooks/nfr-maintainability-rulebook.md +26 -81
  200. package/docs/ja/specdojo/rulebooks/nfr-operations-rulebook.md +32 -70
  201. package/docs/ja/specdojo/rulebooks/nfr-performance-rulebook.md +45 -87
  202. package/docs/ja/specdojo/rulebooks/nfr-reliability-rulebook.md +48 -101
  203. package/docs/ja/specdojo/rulebooks/nfr-security-safety-rulebook.md +44 -80
  204. package/docs/ja/specdojo/rulebooks/nfr-usability-rulebook.md +59 -127
  205. package/docs/ja/specdojo/rulebooks/opd-index-rulebook.md +31 -50
  206. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +42 -109
  207. package/docs/ja/specdojo/rulebooks/opr-index-rulebook.md +29 -42
  208. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +29 -87
  209. package/docs/ja/specdojo/rulebooks/otp-index-rulebook.md +62 -84
  210. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +11 -61
  211. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +91 -106
  212. package/docs/ja/specdojo/rulebooks/pm-change-request-log-rulebook.md +25 -34
  213. package/docs/ja/specdojo/rulebooks/pm-communication-plan-rulebook.md +30 -53
  214. package/docs/ja/specdojo/rulebooks/pm-issue-log-rulebook.md +23 -35
  215. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +27 -45
  216. package/docs/ja/specdojo/rulebooks/pm-organization-rulebook.md +37 -45
  217. package/docs/ja/specdojo/rulebooks/pm-plan-rulebook.md +45 -46
  218. package/docs/ja/specdojo/rulebooks/pm-quality-management-plan-rulebook.md +37 -48
  219. package/docs/ja/specdojo/rulebooks/pm-raci-rulebook.md +25 -29
  220. package/docs/ja/specdojo/rulebooks/pm-risk-register-rulebook.md +28 -35
  221. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +36 -41
  222. package/docs/ja/specdojo/rulebooks/pr-rulebook.md +5 -18
  223. package/docs/ja/specdojo/rulebooks/prj-assumptions-constraints-dependencies-rulebook.md +16 -37
  224. package/docs/ja/specdojo/rulebooks/prj-charter-rulebook.md +23 -97
  225. package/docs/ja/specdojo/rulebooks/prj-comparison-of-alternatives-rulebook.md +39 -57
  226. package/docs/ja/specdojo/rulebooks/prj-issues-and-approach-rulebook.md +43 -116
  227. package/docs/ja/specdojo/rulebooks/prj-scope-rulebook.md +16 -51
  228. package/docs/ja/specdojo/rulebooks/prj-stakeholder-register-rulebook.md +47 -92
  229. package/docs/ja/specdojo/rulebooks/prj-success-criteria-and-acceptance-criteria-rulebook.md +25 -84
  230. package/docs/ja/specdojo/rulebooks/sac-rulebook.md +44 -107
  231. package/docs/ja/specdojo/rulebooks/sf-index-rulebook.md +39 -49
  232. package/docs/ja/specdojo/rulebooks/sf-rulebook.md +42 -49
  233. package/docs/ja/specdojo/rulebooks/sld-rulebook.md +64 -89
  234. package/docs/ja/specdojo/rulebooks/stc-index-rulebook.md +90 -189
  235. package/docs/ja/specdojo/rulebooks/stc-rulebook.md +45 -105
  236. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +6 -12
  237. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +49 -68
  238. package/docs/ja/specdojo/rulebooks/sysd-critical-flows-rulebook.md +51 -60
  239. package/docs/ja/specdojo/rulebooks/sysd-cross-cutting-policy-rulebook.md +46 -50
  240. package/docs/ja/specdojo/rulebooks/sysd-index-rulebook.md +39 -64
  241. package/docs/ja/specdojo/rulebooks/sysd-rulebook.md +47 -60
  242. package/docs/ja/specdojo/rulebooks/trc-requirements-to-specs-rulebook.md +69 -70
  243. package/docs/ja/specdojo/rulebooks/trc-requirements-to-tests-rulebook.md +65 -72
  244. package/docs/ja/specdojo/rulebooks/tsd-index-rulebook.md +35 -46
  245. package/docs/ja/specdojo/rulebooks/tsd-rulebook.md +49 -66
  246. package/docs/ja/specdojo/rulebooks/tsp-index-rulebook.md +64 -139
  247. package/docs/ja/specdojo/rulebooks/uis-rulebook.md +41 -108
  248. package/docs/ja/specdojo/rulebooks/utc-index-rulebook.md +49 -144
  249. package/docs/ja/specdojo/rulebooks/utc-rulebook.md +67 -155
  250. package/docs/ja/specdojo/samples/bds-sample.md +58 -71
  251. package/docs/ja/specdojo/samples/bes-index-sample.md +20 -37
  252. package/docs/ja/specdojo/samples/bes-sample.md +43 -53
  253. package/docs/ja/specdojo/samples/bps-sample.md +42 -54
  254. package/docs/ja/specdojo/samples/br-sample.md +40 -52
  255. package/docs/ja/specdojo/samples/ccd-sample.md +0 -1
  256. package/docs/ja/specdojo/samples/cdr-sample.md +78 -0
  257. package/docs/ja/specdojo/samples/cdsd-sample.md +47 -63
  258. package/docs/ja/specdojo/samples/clis-sample.md +70 -77
  259. package/docs/ja/specdojo/samples/dec-sample.md +2 -3
  260. package/docs/ja/specdojo/samples/ifx-api-sample.yaml +0 -2
  261. package/docs/ja/specdojo/samples/ifx-msg-sample.yaml +0 -2
  262. package/docs/ja/specdojo/samples/job-sequence.yaml +67 -0
  263. package/docs/ja/specdojo/samples/mip-index-sample.md +98 -20
  264. package/docs/ja/specdojo/samples/pm-communication-plan-sample.md +26 -19
  265. package/docs/ja/specdojo/samples/pm-organization-sample.md +39 -50
  266. package/docs/ja/specdojo/samples/pm-plan-sample.md +61 -67
  267. package/docs/ja/specdojo/samples/pm-quality-management-plan-sample.md +31 -45
  268. package/docs/ja/specdojo/samples/pm-raci-sample.md +31 -37
  269. package/docs/ja/specdojo/samples/prj-assumptions-constraints-dependencies-sample.md +32 -48
  270. package/docs/ja/specdojo/samples/prj-charter-sample.md +42 -59
  271. package/docs/ja/specdojo/samples/prj-comparison-of-alternatives-sample.md +55 -61
  272. package/docs/ja/specdojo/samples/prj-success-criteria-and-acceptance-criteria-sample.md +30 -33
  273. package/docs/ja/specdojo/samples/sf-index-sample.md +13 -55
  274. package/docs/ja/specdojo/samples/sf-sample.md +73 -85
  275. package/docs/ja/specdojo/samples/sld-sample.md +60 -79
  276. package/docs/ja/specdojo/samples/uis-sample.md +98 -121
  277. package/docs/ja/specdojo/standards/job-definition-standard.md +24 -9
  278. package/docs/ja/specdojo/templates/cdr-template.md +58 -0
  279. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +2 -1
  280. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +42 -5
  281. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +35 -0
  282. package/docs/specdojo/schemas/v1/job-run.schema.yaml +23 -0
  283. package/docs/specdojo/schemas/v1/job.schema.yaml +63 -2
  284. package/docs/specdojo/schemas/v1/sch-strategy.schema.yaml +2 -2
  285. package/package.json +9 -6
  286. package/templates/antigravity/orchestrator.md +4 -1
  287. package/templates/claude/agents/specdojo-orchestrator.md +4 -1
  288. package/templates/codex/agents/specdojo-orchestrator.toml +4 -1
  289. package/templates/codex/orchestrator.md +4 -1
  290. package/templates/init-exec-defaults.yaml +13 -0
  291. package/templates/lefthook/tools/specdojo-pre-commit.mjs +8 -0
  292. package/templates/opencode/agents/specdojo-orchestrator.md +5 -2
@@ -17,65 +17,64 @@ specdojo:
17
17
 
18
18
  Glossary Documentation Rules
19
19
 
20
- 業務分析・要求定義・設計・テストで参照する用語集を YAML 形式で記述するルールです。用語の意味と境界を定義し、利用者がガイドや画面・CLI で目にする言葉と対応付けます。
20
+ 業務分析・要求定義・設計・テストで使う概念の意味と境界を YAML で定めます。
21
21
 
22
22
  ## 1. 全体方針
23
23
 
24
- - 用語集は、同じ言葉を同じ意味で使うための辞書とする。業務の概念に加え、利用者が扱う操作・状態・役割も対象にする。
25
- - 定義は `locale` の言語で書く。英語名、利用者向けのコマンド名、固有名詞の併記は認めるが、翻訳版の定義は別ファイルにする。
26
- - 領域別に分ける場合は、横断の用語を `gl-common`(対象名を付ける場合は `gl-<対象>-common`)へ集め、同じ概念を複数の用語集に定義しない。
27
- - 業務データ辞書やビジネスルールなどから参照する前に用語 ID を採番し、確定後は変更しない。
24
+ - 業務の概念と、利用者が扱う操作・状態・役割を収録する。
25
+ - 定義は `locale` の言語で書く。英語名・コマンド名・固有名詞は併記可。翻訳版は別ファイルにする。
26
+ - 横断の概念は `gl-common`(対象付きなら `gl-<対象>-common`)へ集める。翻訳版を除き、同じ概念を複数の用語集に定義しない。
27
+ - **共通の運用**: 役割は適用先のメンバー定義、`status` の昇格・承認、改訂と廃止、未決事項の引き継ぎは [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従う。整形・lint はリポジトリの検証で扱い、業務の検証に含めない。
28
28
 
29
29
  ## 2. 位置づけ
30
30
 
31
- - 用語の意味は用語集を正本とし、業務の判定条件、データ項目、操作手順、実装詳細はそれぞれの仕様・設計へ委ねる。
32
- - 領域ごとの冒頭のコメントまたは代表用語の注記で、扱う範囲と共通・他領域の正本を示す。
33
- - 共通メタ情報とリンク記法は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]]、配置は [[specdojo:docs-structure-guide|ドキュメント構成ガイド]] を正本とする。
31
+ - 意味の正本とし、判定条件・データ項目・操作手順・実装詳細は各仕様・設計へ委ねる。
32
+ - 冒頭のコメントまたは代表用語の注記で、対象範囲と共通・他領域の正本を示す。
33
+ - 配置は [[specdojo:docs-structure-guide|ドキュメント構成ガイド]] に従う。
34
34
 
35
35
  ## 3. ファイル命名・ID規則
36
36
 
37
37
  ### 3.1. ファイル命名
38
38
 
39
- - ファイル名は `gl-<対象領域>.yaml` を基本とする(例: `gl-common.yaml`、`gl-sales.yaml`)。
40
- - 同じ領域の翻訳版を併置するときは `gl-<対象領域>-<locale>.yaml` とし、ファイル名・用語集 ID で区別する(例: `gl-sales-ja.yaml`、`gl-sales-en.yaml`)。
41
- - 同梱の完成例のファイル名は `gl-sample.yaml` とする。
39
+ - 基本は `gl-<対象領域>.yaml`(例: `gl-sales.yaml`)。
40
+ - 翻訳版の併置は `gl-<対象領域>-<locale>.yaml` とし、用語集 ID も区別する。
41
+ - 同梱の完成例は `gl-sample.yaml` とする。
42
42
 
43
43
  ### 3.2. ID規約
44
44
 
45
- - 用語集 ID は schema の `^([a-z0-9-]+:)?gl-[a-z0-9-]+$` に従う。成果物の例は `gl-common`、同梱の完成例は authority を付けた `specdojo:gl-sample` とする。
46
- - 用語 ID は `^tm-[a-z0-9-]+$` に従う。新規採番では `tm-<領域>-<概念>` とし、共通用語には `common` など共有範囲を示す接頭辞を使う。
47
- - 用語 ID は同一プロジェクトの用語集をまたいで一意にする。既に確定・参照されている ID は、接頭辞がなくても維持し、整形や領域分割を理由に改名しない。
45
+ - 用語集 ID は `^([a-z0-9-]+:)?gl-[a-z0-9-]+$`(完成例は `specdojo:gl-sample`)。
46
+ - 用語 ID は `^tm-[a-z0-9-]+$`。新規は `tm-<領域>-<概念>` とし、共通には `common` など共有範囲を使う。
47
+ - 参照前に採番し、同一プロジェクトの用語集をまたいで一意にする。確定・参照済み ID は接頭辞がなくても維持する。
48
+ - 翻訳版の新規 ID は原語 ID に小文字の言語接尾辞(例: `-en`)を付ける。`source` に原語の用語集リンク・用語 ID を示す。
48
49
 
49
50
  ## 4. 推奨 Frontmatter 項目
50
51
 
51
- YAML のメタ情報は `specdojo:` で包まずルートに置く。構造と値の制約は `docs/specdojo/schemas/v1/gl.schema.yaml` を正本とし、先頭の modeline から対応 schema を参照する。
52
+ メタ情報はルートに置く。下記 schema を正本とし、先頭の modeline に相対パスで指定する。
52
53
 
53
54
  | 項目 | 説明 | 必須 |
54
55
  | ---------- | -------------------------------------------- | ---- |
55
56
  | `id` | 「ID規約」に従う用語集 ID | ○ |
56
57
  | `type` | `glossary` 固定 | ○ |
57
58
  | `rulebook` | `specdojo:gl-rulebook` | ○ |
58
- | `title` | 対象領域が分かる用語集名 | ○ |
59
+ | `title` | 対象領域を示す用語集名 | ○ |
59
60
  | `locale` | 定義の言語(例: `ja` / `en`) | ○ |
60
61
  | `status` | 文書成熟度。`draft` / `ready` / `deprecated` | ○ |
61
62
 
62
- `status` は schema 上は省略可能だが、共通メタ情報の規約に従って記載する。`ready` への昇格は人間が行う。
63
+ 構造検査は `npm run validate:schema:file -- --schema docs/specdojo/schemas/v1/gl.schema.yaml --data <対象.yaml>`、参照検査は `node packages/docs-lint/bin/specdojo-docs-lint.js glossary-references <対象.yaml>`。ともにエラーなし・終了コード 0 を確認する。modeline は `# yaml-language-server: $schema=<相対パス>`。
63
64
 
64
65
  ## 5. 本文要件
65
66
 
66
67
  ### 5.1. ルートキー要件
67
68
 
68
- - メタ情報に加え、ルートに `terms`(用語オブジェクトの配列)を必ず持つ。
69
- - 掲載範囲の概念を識別できる用語を収録し、定義のない分類名や参照先を残さない。
70
- - schema にないルートキーや用語のキーは追加しない。
69
+ - ルートの `terms` は必須の用語オブジェクト配列とする。
70
+ - 分類や参照先の概念にも定義を持たせる。
71
+ - schema にないキーは追加しない。
71
72
 
72
73
  ### 5.2. `terms` の項目
73
74
 
74
- 各用語の要素は以下のキーを持つ。
75
-
76
75
  | 項目 | 説明 | 必須 |
77
76
  | -------------- | ------------------------------------------------------- | ---- |
78
- | `id` | 用語を安定して識別する用語 ID | ○ |
77
+ | `id` | 安定した用語 ID | ○ |
79
78
  | `term` | 利用者が目にする正式な呼び方 | ○ |
80
79
  | `englishName` | 概念の英語名 | 任意 |
81
80
  | `aliases` | 同じ概念の別名・従来表記の配列 | 任意 |
@@ -83,75 +82,66 @@ YAML のメタ情報は `specdojo:` で包まずルートに置く。構造と
83
82
  | `notes` | 読み手向けの前提・例外・使用文脈 | 任意 |
84
83
  | `category` | 同じ用語集内で分類に使う用語 ID | 任意 |
85
84
  | `relatedTerms` | 同じ用語集内の関連用語 ID の配列 | 任意 |
86
- | `source` | 根拠文書へのリンク、schema のパス・定義名、URL など | 任意 |
85
+ | `source` | 文書リンク・schema のパスと定義名・URL | 任意 |
87
86
  | `status` | 用語の採用状態。`official` / `deprecated` / `candidate` | 任意 |
88
87
  | `example` | 用語を使う短い例文 | 任意 |
89
88
 
90
- 必須は `id`・`term`・`definition` の 3 項目とする。任意項目は説明に必要なものだけ記載し、用語の `status` とルートの文書成熟度を混同しない。
89
+ 任意項目は必要なものだけ記載し、用語の `status` と文書成熟度を区別する。`candidate` は業務の利用者・確認者と用例・根拠を照合し、意味・境界・呼び方の合意後に `official` にする。未合意なら候補に留め、`notes` に論点と利用への影響を示す。
91
90
 
92
91
  ## 6. 記述ガイド
93
92
 
94
93
  ### 6.1. 全体方針・位置づけの判断
95
94
 
96
- 利用者が概念を区別するために必要な語か、どの領域が意味の正本を持つかで収録先を決める。共通事項は「位置づけ」で示す上位標準を参照し、各領域へ再掲しない。
97
-
98
- - 良い例: 販売と在庫の両方で使う「商品」は共通へ置き、販売固有の「つけ残高」は販売へ置く。
99
- - 悪い例: 販売と在庫に同じ「商品」をそれぞれ定義し、更新時にどちらを直すか決まらない。
95
+ - 良い例: 「商品」は共通、「つけ残高」は販売へ置く。
96
+ - 悪い例: 販売と在庫で同じ「商品」を別々に定義する。
100
97
 
101
98
  ### 6.2. ファイル命名・ID の判断
102
99
 
103
- 新規 ID は領域と概念が読める英小文字の名詞を基本とし、略語は読み手に通じるものに限る。既存の確定 ID の維持を、新規の接頭辞規則より優先する。
100
+ 新規 ID は名詞を基本とし、難解な略語は避ける。
104
101
 
105
- - 良い例: 販売の新しい用語に `tm-sales-credit-limit` を採番し、既存の `tm-accounts-receivable` は維持する。
106
- - 悪い例: 領域ごとに `tm-status` を新設する、または接頭辞をそろえるために確定済み ID を改名する。
102
+ - 良い例: 新規は `tm-sales-credit-limit`、既存の `tm-accounts-receivable` は維持する。
103
+ - 悪い例: 領域ごとに `tm-status` を新設する、整形で確定 ID を改名する。
107
104
 
108
105
  ### 6.3. メタ情報・ルート構造の判断
109
106
 
110
- `title` で対象領域、`locale` で定義の言語が分かり、メタ情報と `terms` が同じ階層にあるかを確認する。
111
-
112
- - 良い例: `title: 用語集(販売)`、`locale: ja` とルートの `terms` を持つ。
113
- - 悪い例: 全メタ情報を `specdojo:` の下に入れる、または `terms` を文章で代用する。
107
+ - 良い例: `title: 用語集(販売)`、`locale: ja` とルートの `terms`。
108
+ - 悪い例: `specdojo:` で全体を包む、`terms` を文章で代用する。
114
109
 
115
110
  ### 6.4. 用語の見出し・英語名の判断
116
111
 
117
- `term` はガイド・画面や CLI の表示・コマンド名で利用者が目にする言い方に合わせ、言い換えは `aliases` に置く。英語の用語と `englishName` は小文字にし、SpecDojo の概念名として大文字が定着したもの(Kata など)と固有名詞(SpecDojo など)だけを例外とする。別名として過去の表記を残すことは認める。
112
+ `term` はガイド・画面・CLI での呼び方に合わせ、言い換えや過去の表記は `aliases` に置く。英語の見出しと `englishName` は小文字とし、大文字が定着した概念名(Kata)と固有名詞(SpecDojo)は例外とする。
118
113
 
119
- - 良い例: `term: つけ`、`englishName: sale on credit`、`aliases: [ツケ, 掛け売り]`。英語の見出しなら `term: job run` とする。
120
- - 悪い例: 利用者が「つけ」と呼ぶものを `term: 売掛債権取引` とする、または `englishName: Sale On Credit` とする。
114
+ - 良い例: `term: つけ`、`englishName: sale on credit`、`aliases: [ツケ, 掛け売り]`。
115
+ - 悪い例: 「つけ」を `term: 売掛債権取引`、英語名を `Sale On Credit` とする。
121
116
 
122
117
  ### 6.5. 定義・注記・根拠の判断
123
118
 
124
- `definition` は一文で意味と境界が分かる説明を基本とする。`notes` は前提・例外・使用文脈だけを補い、定義の繰り返しや、`category`・`relatedTerms` の指定方法など YAML の書き方を含めない。設定キーやコマンドとの対応は概念の理解に必要な範囲で示せるが、項目名の羅列を避け、独立して説明できる概念が増えたら用語を分ける。
119
+ `definition` は一文を基本とする。`notes` は定義を繰り返さない。設定・コマンドとの対応は理解に必要な範囲に絞り、独立した概念は分ける。
125
120
 
126
- - 良い例: つけの注記を「店主が認めた常連客だけが利用する。」とし、残高と限度額は別の用語にする。
127
- - 悪い例: 「構成要素の `category` に本用語を指定する。」と注記する、または定義を「つけとはツケのこと。」で済ませる。
128
- - schema の条件付き規則は、用語間の関係を短く説明し、条件分岐・必須キーの一覧は写さない。根拠は `source` に実在する文書のリンクや schema のパス・定義名で示す。
129
- - 良い例: 「つけは常連客に認める後払いの販売で、つけ残高を管理する。」と関係を示し、厳密な条件は根拠へ委ねる。
130
- - 悪い例: 注記へ schema の `if` / `then` と必須項目をそのまま転記する。
131
- - 未確定の内容には共通ラベル(`_TODO_` / `_UNDECIDED_` / `_ASSUMPTION_`)を使い、確定時には解消する。
121
+ - 良い例: つけの注記は「店主が認めた常連客だけが利用する。」とし、残高・限度額は別の用語にする。
122
+ - 悪い例: 定義を「つけとはツケのこと。」で済ませる。
123
+ - schema の条件付き規則は用語間の関係で短く説明し、厳密な条件は `source` へ委ねる。
124
+ - 良い例: 「つけは常連客に認める後払いの販売で、つけ残高を管理する。」
125
+ - 悪い例: schema の `if` / `then` と必須キー一覧を注記へ写す。
132
126
 
133
127
  ### 6.6. 分類・関連用語の判断
134
128
 
135
- ほかの用語の分類に使う概念も用語として定義し、`category` でまとめる。`relatedTerms` は同じ文脈で理解すべき用語に絞る。いずれも同じ用語集内の用語 ID だけを指定する。
129
+ `category`・`relatedTerms` は同じ用語集の ID に限り、関連語は同じ文脈で理解すべきものに絞る。領域外の関係は `notes` または `source` に正本リンクと必要な用語 ID を示す。
136
130
 
137
- - 良い例: 「販売」を定義して、同じファイルの「つけ」の `category` にその ID を指定する。
138
- - 悪い例: 分類名を未定義の文字列にする、または共通用語を分類に使うためだけに領域別の用語集へ複製する。
139
- - 領域をまたぐ関係は `notes` または `source` に正本の用語集への文書リンクと必要なら用語 ID を記し、`category`・`relatedTerms` には入れない。
140
- - 良い例: 共通用語が別ファイルなら「商品の定義は共通用語集を参照する」と文書リンクで案内する。
141
- - 悪い例: 別ファイルにしかない `tm-common-product` を `relatedTerms` に指定する。
142
- - `validate:schema` はファイル内の用語 ID の重複と参照先の存在を検証する。用語集をまたぐ ID の一意性と同じ概念の重複定義は、別途横断で照合する。
131
+ - 良い例: 同じファイルの「販売」を分類に使い、別ファイルの「商品」は文書リンクで案内する。
132
+ - 悪い例: 未定義の分類名や別ファイルの ID を指定する、分類のためだけに共通用語を複製する。
133
+ - 参照検査が扱うのはファイル内の ID 重複と参照先の存在だけで、BDD・BR の参照は検査しない。業務の受入確認では用語集を横断して ID の一意性・翻訳以外の概念重複を照合し、参照元で意味と呼び方が一致すれば合格とする。
143
134
 
144
135
  ### 6.7. 改訂・廃止時の判断
145
136
 
146
- 意味の変更・廃止では、共通メタ情報標準の「文書の改訂・廃止とライフサイクル変更管理」に従い、BA が用語 ID を参照するデータ辞書・業務ルール・画面や CLI の用語を洗い出し、DEV が実装、QE がテスト・受入条件の追従を確認する。廃止・確定は PO が判断し、PM が移行作業を管理する。schema にない変更管理項目は YAML に増やさず、個票などの変更記録へ残す。
137
+ ID・意味・採用状態の変更影響は、BDD・BR の用語参照、画面・CLI、実装、テスト・受入条件、表示ページで照合する。表示ページは YAML から `specdojo build --only yaml-pages` で再生成し、定義・分類・関連用語の一致を確認する。
147
138
 
148
- - 良い例: 意味が変わる用語は新しい ID で定義し、旧用語は `status: deprecated` として後継を注記し、参照元を更新する。
149
- - 悪い例: 旧 ID の定義を別の意味に上書きする、または参照元を確認せず用語を削除する。
139
+ - 良い例: 意味が変わる語は新 ID とし、旧用語は `status: deprecated` と後継の注記を持ち、参照元を更新する。
140
+ - 悪い例: 旧 ID を別の意味に上書きする、参照元を確認せず削除する。
150
141
 
151
142
  ## 7. 禁止事項
152
143
 
153
- - 用語 ID を未採番・重複のままにすること、意味の違う用語に使い回すこと、確定後に変更すること。
154
- - `definition` を曖昧に書くこと(例: 「正しく処理される」「いい感じの在庫」など)。
155
- - 用語の説明へ物理テーブル名・内部クラス名・SQL 全文などの実装詳細や、仕様・schema の条件一覧を持ち込むこと。
156
- - 同じ概念を別名・別領域で重複定義し、別名または正本への参照にまとめないこと。
157
- - 読み手向けの意味を補わない編集手順・YAML 記法のメモを `notes` に書くこと。
144
+ - 用語 ID の未採番・重複・意味の異なる語への再利用・確定後の改名。
145
+ - 意味を識別できない定義(「いい感じの在庫」など)。
146
+ - 別名を別概念として定義すること、翻訳以外で領域間に同じ概念を複製すること。
147
+ - 概念の説明を実装詳細・条件一覧で代用すること、編集手順・YAML 記法を `notes` に書くこと。
@@ -16,100 +16,93 @@ specdojo:
16
16
 
17
17
  Infrastructure Flow Diagram (IFD) Documentation Rules using Mermaid
18
18
 
19
- 実行環境・ネットワーク・信頼境界と、主要な通信経路を合意するための規約を定める。配置と依存の判断に集中し、詳細設定や操作手順の正本を増やさない。
19
+ 実行環境・ネットワーク・信頼境界と主要な通信経路を合意するための規約を定める。
20
20
 
21
21
  ## 1. 全体方針
22
22
 
23
- - 上位アーキテクチャの要素を実行場所へ対応付け、配置の事実・仮定・未決事項を区別する。
24
- - 同じホスト上でも管理主体・到達範囲が異なる境界は区別する。枠だけで隔離やアクセス制御の実装済みを保証しない。
25
- - 通信は目的、起点、終点、利用条件、境界を越える情報を示す。障害の影響範囲と検証対象を識別できる粒度にする。
26
- - CIDR、IP、ポート、台数、版、認証値、FW・IAM 設定、コマンド構文は載せない。必要な詳細は技術構成・連携・運用の正本へ委ねる。
23
+ - 上位の要素を実行場所へ対応付け、配置の事実・仮定・未決事項を区別する。
24
+ - 同じホスト上でも管理主体・到達範囲が異なる境界は区別する。
25
+ - 通信は障害の影響範囲と検証対象を識別できる粒度で示す。
26
+ - CIDR、IP、ポート、台数、版、認証値、FW・IAM 設定、コマンド構文は載せず、技術構成・連携・運用の正本へ委ねる。
27
+ - 共通の運用: 役割の割り当ては適用先のメンバー定義に、`status` の昇格と承認、改訂と廃止、未決事項の引き継ぎは [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従う。文書の整形・lint はリポジトリの検証で扱い、成果物の検証観点に含めない。
27
28
 
28
29
  ## 2. 位置づけと用語定義
29
30
 
30
- | 用語・文書 | 本書での意味・責務 |
31
- | ------------------ | ------------------------------------------------------------------------------------------ |
32
- | 実行環境 | ホスト・コンテナ・外部サービスなど、処理やデータを置く単位 |
33
- | ネットワーク境界 | 到達経路・接続条件が変わる区切り。必ずしも物理ネットワークと一致しない |
34
- | 論理ゾーン | 管理主体、公開範囲、情報の持ち出し条件を検討する区切り |
35
- | 上位構成図 | 処理・データ・外部依存の責務を定義する入力。論理的なコンテナと実行用コンテナを同一視しない |
36
- | 詳細設計・運用文書 | 接続設定、認証方式、監視閾値、復旧手順を管理する委譲先 |
31
+ | 用語 | 本書での意味 |
32
+ | ---------------- | ------------------------------------------------------------------ |
33
+ | ネットワーク境界 | 到達経路・接続条件が変わる区切り。物理構成と一致するとは限らない |
34
+ | 論理ゾーン | 管理主体、公開範囲、情報の持ち出し条件を検討する区切り |
35
+ | 上位構成図 | 責務を定義する入力。論理的なコンテナと実行用コンテナを同一視しない |
37
36
 
38
37
  ## 3. ファイル命名・ID規則
39
38
 
40
- - ファイル名は `ifd-<target>.md` とし、対象システムまたは配置範囲を英小文字・数字・ハイフンで表す。
41
- - `id` はファイル名の stem と対応させる。名前空間・配置の共通規則は [[specdojo:docs-structure-guide|ドキュメント構造ガイド]] を正とする。
42
- - Mermaid のノード ID と表示名を分離する。文書内で一意な ID を使い、改訂時も同じ要素・経路の ID を維持する。
39
+ - ファイル名は `ifd-<target>.md` とし、`id` は stem と対応させる。共通規則は [[specdojo:docs-structure-guide|ドキュメント構造ガイド]] を正とする。
40
+ - Mermaid のノード ID と表示名を分離し、改訂時も同じ要素・経路の ID を維持する。
43
41
 
44
42
  ## 4. 推奨 Frontmatter 項目
45
43
 
46
- 共通の値・構文は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] と成果物 Frontmatter schema を正とする。
44
+ 共通の値・構文は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] を正とする。
47
45
 
48
46
  | 項目 | 扱い | IFD での用途 |
49
47
  | ------------------------ | -------- | ---------------------------------------------------- |
50
- | `id` / `type` / `status` | 必須 | 文書の識別、`architecture` 分類、成熟度 |
51
48
  | `rulebook` | 必須 | `specdojo:ifd-mermaid-rulebook` を指定する |
52
- | `owner` | 推奨 | 配置・境界設計を担うロール |
53
49
  | `based_on` | 条件付き | 直接の根拠となる上位構成図。単なる参考文書は含めない |
54
50
  | `part_of` / `supersedes` | 条件付き | 所属・置き換え関係がある場合に記載する |
55
51
 
56
52
  ## 5. 本文要件
57
53
 
58
- 見出し順・記入欄の骨組みは frontmatter で宣言した template を正本とする。以下は内容の成立条件であり、同じ表を全文書へ複製する指示ではない。
54
+ 骨組みは template を正本とし、以下は内容の成立条件である。
59
55
 
60
- | 内容 | 必須性 | 目的・判定条件 |
61
- | ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
62
- | 概要 | 必須 | 対象環境、図で判断すること、上位入力、対象外を識別できる |
63
- | インフラ構成図 | 必須 | 実行場所、必要な境界、主要経路を Mermaid で示し、凡例で向き・線種・省略を説明する |
64
- | 配置と境界の定義 | 必須 | 図中の要素に管理主体・保持情報・到達条件を対応付け、上位要素の配置または対象外の扱いを示す。代替配置がある場合は適用条件と置き換わる要素を区別する |
65
- | 通信経路と情報の境界 | 必須 | 図と本文の経路 ID・起点・終点が対応し、目的、情報の要点、利用条件、詳細の正本または引き継ぎ先を追える |
66
- | 技術前提・制約と検証観点 | 必須 | 隔離・認証・公開に関する前提と、境界別の障害影響・観測対象・主確認ロールを示す |
67
- | メモ / 将来課題 | 条件付き | 仮定・未決事項がある場合、対象、影響、担当、解消条件・引き継ぎ先を残す |
56
+ | 内容 | 必須性 | 判定条件 |
57
+ | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------ |
58
+ | 概要 | 必須 | 対象環境、図で判断すること、上位入力、対象外を識別できる |
59
+ | インフラ構成図 | 必須 | 実行場所、必要な境界、主要経路を Mermaid で示し、凡例で向き・線種・省略を説明する |
60
+ | 配置と境界の定義 | 必須 | 要素に管理主体・保持情報・到達条件を対応付け、上位要素の配置か対象外かを示す。代替配置は適用条件を示す |
61
+ | 通信経路と情報の境界 | 必須 | 図と本文の経路 ID・起点・終点が対応し、目的、情報の要点、利用条件、詳細の正本を追える |
62
+ | 技術前提・制約と検証観点 | 必須 | 隔離・認証・公開の前提と、境界別の障害影響・観測対象を示す |
63
+ | メモ / 将来課題 | 条件付き | 仮定・未決事項がある場合、論点と影響(当面の扱い)を残す |
68
64
 
69
65
  ### 5.1. Mermaid の表現規約
70
66
 
71
- - `flowchart LR` を使う。矢印の意味は依頼・参照・転送などの主たる起点から終点への向きとし、通常の応答は同じ線に含める。独立した逆方向の起動だけを別線にする。
72
- - `subgraph` は最大 3 階層とする。実行環境・ネットワーク・論理ゾーンのうち必要な境界だけを描き、各枠が何の区切りか明記する。階層数を埋めるための枠は作らない。
73
- - 表示名は役割を主語とする。配置や接続先の識別に必要な製品名は「推論サービス(製品名)」のように補記してよい。製品名だけで責務を表さない。
74
- - 処理は矩形、DB は円筒、ファイル保管は角丸を基本とする。形状・色・絵文字だけに意味を持たせず文字で識別できるようにする。
75
- - 経路ラベルに ID と通信目的を付ける。プロトコル名だけのラベルは使わない。線種を分ける場合は凡例で意味を定義する。
76
- - 中継を省略して論理的な経路を一本で描く場合は、図の近傍で省略した中継と到達条件を説明する。中継方式が未確定なら仮定とし、直接接続が許可されている図と誤読させない。
77
- - 装飾は任意とし、色を使う場合は `classDef` で役割の分類を統一する。交差が判断を妨げる場合は範囲を分割し、共有要素と経路 ID を対応付ける。
67
+ - `flowchart LR` を使う。矢印は主たる起点から終点へ向け、応答は同じ線に含める。独立した逆方向の起動だけを別線にする。
68
+ - `subgraph` は最大 3 階層とし、必要な境界だけを描いて各枠が何の区切りか明記する。
69
+ - 表示名は役割を主語とし、製品名は「推論サービス(製品名)」のように補記する。
70
+ - 処理は矩形、DB は円筒、ファイル保管は角丸を基本とし、形状・色・絵文字だけに意味を持たせない。
71
+ - 経路ラベルに ID と通信目的を付け、プロトコル名だけにしない。線種を分ける場合は凡例で定義する。
72
+ - 中継を省略して一本で描く場合は、図の近傍で中継と到達条件を説明し、直接接続と誤読させない。
73
+ - 色は `classDef` で役割の分類を統一する。交差が判断を妨げる場合は範囲を分割し、共有要素と経路 ID を対応付ける。
74
+ - 図の確認: 「インフラ構成図」章の全 Mermaid ブロックの構文を `npm run lint:mermaid` で確かめ、描画プレビューで表示名・経路ラベル・枠名が読めること、枠の包含が「配置と境界の定義」と一致することを確かめる。
78
75
 
79
76
  ## 6. 記述ガイド
80
77
 
81
- 共通のメタ情報・リンク記法は上位標準を正本とし、本章では IFD 固有の判断だけを扱う。
82
-
83
78
  ### 6.1. 概要
84
79
 
85
- 対象環境と判断範囲を先に選ぶ。良い例は「店舗端末から共有サービスまでの到達範囲を示し、通信不能時の切り分けに使う」。悪い例は「システム全体を説明する」で、配置判断の範囲が選べない。
80
+ 対象環境と判断範囲を先に選ぶ。良い例は「店舗端末から共有サービスまでの到達範囲を示し、通信不能時の切り分けに使う」。悪い例は「システム全体を説明する」。
86
81
 
87
82
  ### 6.2. インフラ構成図
88
83
 
89
- 枠を越えるごとに実行場所・接続条件・管理主体のどれが変わるかで描き分ける。良い例は「店舗端末と外部保管サービスを別枠にし、送信する記録をラベルにする」。悪い例は「同じ製品なので外部サービスも端末の枠に入れる」。仮の経路は図の近傍にも仮定と記す。入口の中継を省略するなら「入口経由の記録要求を論理線で表す」と注記し、端末から内部サービスへ直接到達できるように描かない。
84
+ 枠を越えるごとに実行場所・接続条件・管理主体のどれが変わるかで描き分ける。良い例は「店舗端末と外部保管サービスを別枠にし、送信する記録をラベルにする」。悪い例は「同じ製品なので外部サービスも端末の枠に入れる」。
90
85
 
91
86
  ### 6.3. 配置と境界の定義
92
87
 
93
- 配置表では図にない管理責務・保持情報を補う。推奨列は「図中の環境・要素、上位要素、管理主体、情報・到達条件」。良い例は「作業記録は端末側、外部には送信対象だけを渡す案」。悪い例は「Private 枠なので安全」で、アクセス制御の根拠がない。
88
+ 図にない管理責務・保持情報を補う。推奨列は「図中の環境・要素、上位要素、管理主体、情報・到達条件」。良い例は「作業記録は端末側、外部には送信対象だけを渡す案」。悪い例は「Private 枠なので安全」。
94
89
 
95
- 代替配置は同時稼働か選択肢かを判断し、後者なら置き換え後の保持範囲・到達性を確認対象にする。良い例は「コンテナ実行の代わりにホストで同じ役割を実行し、書込範囲を再確認する」。悪い例は「両環境に同名の処理を置き、稼働条件を示さない」。上位の責務は配置を変えても引き継ぐ。
90
+ 代替配置が選択肢なら、置き換え後の保持範囲・到達性を確認対象にする。良い例は「ホストで同じ役割を実行し、書込範囲を再確認する」。悪い例は「両環境に同名の処理を置き、稼働条件を示さない」。
96
91
 
97
92
  ### 6.4. 通信経路と情報の境界
98
93
 
99
- 条件付きの外部依存を常時必須の経路と混ぜない。推奨列は「経路 ID、起点 → 終点、目的・情報、利用条件・詳細の委譲先」。良い例は「共有時だけ控えを外部へ送り、接続・認証の契約は連携仕様で定める」。悪い例は「全データを同期する」で、情報範囲と正本の位置が不明である。
94
+ 条件付きの外部依存を常時必須の経路と混ぜない。推奨列は「経路 ID、起点 → 終点、目的・情報、利用条件・詳細の委譲先」。良い例は「共有時だけ控えを外部へ送り、接続・認証の契約は連携仕様で定める」。悪い例は「全データを同期する」。
100
95
 
101
96
  ### 6.5. 技術前提・制約と検証観点
102
97
 
103
- 境界が成立する条件と、条件が崩れたときに観測するものを結ぶ。良い例は「別ホストへの到達不能、サービスの応答欠落、記録の保存失敗を分けて観測する」。悪い例は「トンネルがつながるので作業も成功する」。検証設計への入力と実施済みの証跡を区別し、監視対象は識別するが、閾値や復旧コマンドを再定義しない。
98
+ 境界が成立する条件と、崩れたときに観測するものを結ぶ。良い例は「別ホストへの到達不能、応答欠落、保存失敗を分けて観測する」。悪い例は「トンネルがつながるので作業も成功する」。検証設計への入力と実施済みの証跡を区別し、閾値や復旧コマンドを再定義しない。
104
99
 
105
100
  ### 6.6. メモ / 将来課題
106
101
 
107
- 不明点が承認・検証・運用のどこを止めるかで影響を具体化する。良い例は「公開先未決。ARC が到達範囲を整理し、PO の公開判断後に配置へ反映する」。悪い例は「後で検討する」。単なる調査待ちと仮定は共通ラベルで区別する。
102
+ 不明点が配置・境界・経路のどこに効くかで影響を具体化する。良い例は「公開先が未決のため公開経路は仮定とし、決まったら枠と経路を直す」。悪い例は「後で検討する」。
108
103
 
109
104
  ## 7. 禁止事項
110
105
 
111
106
  - 上位図の責務を変更したり、業務判断・公開可否・製品採択を根拠なく確定したりしない。
112
107
  - 論理ゾーンやトンネルの存在だけから、隔離・認証・情報非保持を保証しない。
113
108
  - 詳細設定・schema・リファレンスの値、構文、構造を複製しない。秘密値や個人固有の接続先を載せない。
114
- - 完成図の例を本書に埋め込まない。対応する型の所在は frontmatter の宣言で管理する。
115
- - 改訂・廃止で経路や境界が変わる場合、追従先を省略しない。ARC が上位構成図・連携設計、QE が検証対象、OPS が監視・運用参照、PO が公開判断への影響を確認する。ライフサイクル手続きは共通メタ情報標準に従う。
@@ -14,23 +14,22 @@ specdojo:
14
14
 
15
15
  外部システム(仕入先、会計、物流、決済など)と連携する **1つのREST APIインターフェース**を、**OpenAPI形式**(YAML 1ファイル)で定義します。
16
16
 
17
- EAPIS は ESIL(外部システムIF一覧)から参照される「詳細仕様」です。
18
- ESIL 側の `spec_ref: ifx-api-...` は、このEAPISのID(およびファイル名)と対応させます。
17
+ EAPIS は ESIL(外部システムIF一覧)から参照される「詳細仕様」で、ESIL 側の `spec_ref: ifx-api-...` をこの EAPIS の ID とファイル名に対応させます。
18
+
19
+ `status` の昇格と承認、改訂と廃止は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従い、本書では言い直しません。
19
20
 
20
21
  ## 1. ファイル規約
21
22
 
22
- - ファイル名: `ifx-api-<短い英小文字ハイフン>.yaml`
23
- - ESILからの参照: `spec_ref: ifx-api-...`(例: `ifx-api-payment`)
23
+ - ファイル名: `ifx-api-<短い英小文字ハイフン>.yaml`(例: `ifx-api-payment`)
24
24
  - 1ファイル = 1つのAPI(1つの外部連携インターフェース)
25
25
 
26
26
  ## 2. OpenAPIバージョン
27
27
 
28
- - **OpenAPI 3.0.3**(推奨)または **OpenAPI 3.1.x** を利用する
29
- - 本リポジトリでは互換性のため **3.0.3** を第一候補とする
28
+ - 互換性のため **OpenAPI 3.0.3** を第一候補とし、**3.1.x** も使えます。
30
29
 
31
30
  ## 3. 記載方針(必須)
32
31
 
33
- - **外部との合意に必要な最小十分**を記載する(内部実装の都合は書かない)
32
+ - **外部との合意に必要な最小十分**を記載する
34
33
  - `paths` は **実際に提供/利用するエンドポイントのみ**定義する
35
34
  - `operationId` は英字で一意にする(例: `createPayment`)
36
35
  - スキーマは `components/schemas` に集約し、`$ref` で参照して使い回す
@@ -54,22 +53,19 @@ ESIL 側の `spec_ref: ifx-api-...` は、このEAPISのID(およびファイ
54
53
  - `servers`(少なくとも1つ)
55
54
  - `paths`(少なくとも1つ)
56
55
 
57
- ## 4.1 メタ情報(x-spec-meta)
58
-
59
- 仕様のトレーサビリティ管理のため、以下を `x-spec-meta` に含めます。
56
+ ### 4.1. メタ情報(x-spec-meta)
60
57
 
61
- | キー | 説明 | 必須 |
62
- | ---- | ---- | ---- |
63
-
64
- | id | API仕様ID(`ifx-api-...`)、ESILの `spec_ref` と対応 | ○ |
65
- | type | `api` 固定 | ○ |
66
- | rulebook | `specdojo:ifx-api-rulebook` | ○ |
67
- | status | `draft` / `ready` / `deprecated` | ○ |
58
+ | キー | 説明 | 必須 |
59
+ | -------- | ---------------------------------------------------- | ---- |
60
+ | id | API仕様ID(`ifx-api-...`) | ○ |
61
+ | type | `api` 固定 | ○ |
62
+ | rulebook | `specdojo:ifx-api-rulebook` | ○ |
63
+ | status | ドキュメントメタ情報標準の値 | ○ |
68
64
  | based_on | 根拠となる他仕様のIDリスト(例: `["ifx-api-auth"]`) | 任意 |
69
65
 
70
66
  ## 5. エラー定義(推奨)
71
67
 
72
- 外部連携では、少なくとも以下のエラーレスポンスを定義します。
68
+ 外部連携では、少なくとも以下のエラーレスポンスを定義し、共通形式(例: `components/schemas/ErrorResponse`)を各 operation から参照します。
73
69
 
74
70
  - `400`(入力不正)
75
71
  - `401`(認証)/ `403`(認可)
@@ -77,5 +73,3 @@ ESIL 側の `spec_ref: ifx-api-...` は、このEAPISのID(およびファイ
77
73
  - `409`(競合)
78
74
  - `429`(レート制限)
79
75
  - `500`(内部エラー)
80
-
81
- 共通形式(例: `components/schemas/ErrorResponse`)を用意し、各operationから参照する運用を推奨します。
@@ -14,21 +14,19 @@ specdojo:
14
14
 
15
15
  External Command Interface Specification (ECIS) Documentation Rules
16
16
 
17
- 外部 CLI プロセスを起動する連携について、実行契約、入出力の約束(渡すもの・受け取るもの・終了コードの意味・作るファイル・副作用・失敗の扱い)、認証注入を YAML 1 ファイルで定義します。引数・オプションの表は持たず、正本(コマンドリファレンスや設定・ガイド)を参照して実装重複を排除します。
17
+ 外部 CLI プロセスとの実行契約、入出力、終了判定、副作用、失敗処置、認証注入を YAML 1 ファイルで定義する基準を定めます。
18
18
 
19
19
  ## 1. 全体方針
20
20
 
21
- - **1 連携 1 ファイル**: 一つの実行目的と共通の入出力契約を単位とする。CLI やサブコマンドが同じでも、目的・権限・出力契約が異なる場合は分割する。複数 provider をまとめる場合は、共通契約と差異を解決する正本を示す。
22
- - **合意境界に絞る**: 渡すもの、受け取るもの、作るファイル、終了状態、副作用、失敗時の処置を定める。引数・オプション表、起動テンプレート全文、内部実装は転載しない。
23
- - **正本を分担する**: 共通事項は上位の外部 I/F 一覧・設計、値・構文・構造の制約は対応 schema、起動方法は設定・リファレンスを参照する。本書は各キーに必要な判断情報と記述規約を定める。
24
- - **起動方式を事実に合わせる**: 原則はシェルを経由しない。設定を正本とするシェル起動の例外条件は「コマンドと正本参照」に従い、実装と異なる方式を仕様上だけ宣言しない。
25
- - **秘密値を持たない**: 認証は注入方式・参照名・管理境界で表す。秘密値を本文、入力例、出力例、ログに含めない。
21
+ - **1 連携 1 ファイル**: 実行目的と入出力契約を単位とし、同じ CLI でも目的・権限・出力契約が異なれば分割する。複数 provider をまとめる場合は、共通契約と差異の正本を示す。
22
+ - **正本を分担する**: 共通事項は上位の外部 I/F 一覧・設計、構造・値の制約は schema、起動方法は設定・リファレンスへ委ね、プロセス境界の判断情報に絞る。
23
+ - **起動方式を事実に合わせる**: 原則はシェルを経由しない。例外条件は「コマンドと正本参照」に従う。
24
+ - **共通の運用**: 役割の割り当ては適用先のメンバー定義に、`status`・承認・改訂と廃止・未決事項の登録簿への引き継ぎは [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従う。文書の整形・lint・構造検証はリポジトリの検証で扱い、業務の受入確認に含めない。
26
25
 
27
26
  ## 2. 位置づけ
28
27
 
29
- - ESIL(外部システム I/F 一覧)は連携の存在・方向・目的を示し、本仕様は `spec_ref` の先でプロセス境界の契約を定める。API・ファイル・メッセージ連携が本体で CLI が操作手段にすぎない場合は、各方式の仕様を正本とする。
28
+ - ESIL(外部システム I/F 一覧)の `spec_ref` の先でプロセス境界の契約を定める。API・ファイル・メッセージ連携の操作手段として CLI を使う場合は、各方式の仕様を正本とする。
30
29
  - 起動方法の正本は対象によって選ぶ。SpecDojo 自身のコマンドはコマンドリファレンス、SpecDojo が起動する AI provider CLI は起動設定の `command_template` と [[specdojo:exec-config-guide|exec 設定ガイド]]、その他の外部 CLI は公式リファレンスや製品マニュアルを参照する。
31
- - ARC は境界・制約・正本分担、DEV は起動と結果判定の実装可能性、QE は正常・異常・再試行の検証可能性、PO / BA は実行目的と副作用の業務上の妥当性を確認する。
32
30
 
33
31
  ## 3. ファイル命名・ID規則
34
32
 
@@ -39,15 +37,14 @@ External Command Interface Specification (ECIS) Documentation Rules
39
37
 
40
38
  ## 4. 先頭メタ項目
41
39
 
42
- - YAML は Frontmatter を持たない。先頭メタ項目の共通原則は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] の「独立 YAML データファイルのメタ情報」に従う。
43
- - 成果物は `type: api`、再利用可能な雛形は `type: template` とし、`rulebook: specdojo:ifx-cmd-rulebook` を指定する。`title` で対象と実行目的を識別する。項目の必須性・型・許容値は `docs/specdojo/schemas/v1/ifx-cmd.schema.yaml` を正本とする。
44
- - 成果物の状態(`status`)は `draft`(作成・改訂中)、`ready`(確定・承認済み)、`deprecated`(非推奨・廃止予定)のいずれかを指定する。成果物の状態を agent が独断で確定(`ready`)へ昇格させない。
45
- - `based_on` には実際に確認した直接の根拠だけを書く。カタログ管理下では `depends_on` の推移閉包内に限定し、起動方法の参照先を示す `command.reference` と役割を混同しない。
40
+ - 先頭メタ項目と雛形自身のメタ情報は、[[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] の「独立 YAML データファイルのメタ情報」と「生成物メタ情報雛形(`metadata_template`)」に従う。
41
+ - 成果物(雛形では `metadata_template` 内)は `type: api`、`rulebook: specdojo:ifx-cmd-rulebook` とし、`title` で対象と実行目的を識別する。
42
+ - `based_on` は作成根拠、`command.reference` は起動方法の正本参照として区別する。
46
43
  - メタ項目の `version` は呼び出し契約の改版、`command.version_constraint` は CLI の対応バージョンを表す。
47
44
 
48
45
  ## 5. 本文要件
49
46
 
50
- YAML の構造、入れ子キー、型、列挙値は `docs/specdojo/schemas/v1/ifx-cmd.schema.yaml` を参照する。検証対象・コマンド・期待結果は「成果物の検証手順」に従う。以下は契約として満たす内容要件であり、schema が互換性のため任意としている項目も、ここで必須とした場合は記述する。
47
+ 構造・型・許容値は `docs/specdojo/schemas/v1/ifx-cmd.schema.yaml` を正本とする。以下は契約の内容要件であり、schema で任意の項目も、本書で必須とした場合は記述する。
51
48
 
52
49
  | 対象キー | 必須性 | 契約として定める内容 |
53
50
  | ---------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
@@ -60,35 +57,35 @@ YAML の構造、入れ子キー、型、列挙値は `docs/specdojo/schemas/v1/
60
57
  | `execution` | 必須 | 作業ディレクトリ、時間・並列実行・ネットワークの制約、冪等性の成立条件または保証できない理由 |
61
58
  | `error_handling` | 必須 | 再試行の対象と上限・待機方式、タイムアウト、出力解析失敗、認証失敗に対する個別の処置 |
62
59
 
63
- schema の後方互換性定義として残されている `arguments` の各項目(種別 `kind` の `argument` / `option` / `positional`、値の供給元 `value_source` の `literal` / `generated` / `config` / `secret` / `user_input`)は、過去の既存仕様との互換性のための定義である。新規作成および改訂では引数表を持たず(PJR-4N3R)、正本参照(`command.reference`)および入出力の約束(`streams`・`files`・`exit_codes`・`side_effects`)へ一本化する。
60
+ `arguments` は既存仕様との後方互換性のための定義である。新規作成・改訂では引数表を持たず、`command.reference` と入出力の契約へ一本化する。
64
61
 
65
62
  ## 6. 記述ガイド
66
63
 
67
64
  ### 6.1. 連携単位とメタ情報
68
65
 
69
- - **判断基準**: ESIL の連携目的と成功後の状態が対応し、1 ファイルを一つの契約として検証できること。共通事項は上位を参照し、同じ provider 一覧や設定値を複数キーへ繰り返さない。
70
- - **改訂・廃止**: [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] の「文書の改訂・廃止とライフサイクル変更管理」に従う。BA は ESIL の参照行と呼び出し元の業務完了・回復条件、ARC は正本分担と制約、DEV は起動設定・入出力処理、QE は成功・失敗・再試行の検証への影響を確認する。移行の追跡は PM、廃止・置き換えの承認は PO が担う。
66
+ - **判断基準**: ESIL の目的と成功後の状態が対応し、1 ファイルを一つの契約として検証できること。provider 一覧や設定値を複数キーへ繰り返さない。
67
+ - **影響の照合先**: ESIL の参照行、呼び出し元の業務完了・回復条件、起動設定・入出力処理、正常・異常・再試行の検証を照合する。
71
68
  - **良い例**: 読取と更新を別 ID にし、`title` に対象と目的を書く。provider ごとに実行ファイルが変わるときは、`executable` に設定の該当キーから解決する旨を示し、一覧自体は設定へ委ねる。
72
69
  - **悪い例**: 一つの仕様に読取・登録・削除を混在させる。設定の provider 一覧を目的・実行ファイル・コメントへそれぞれ転載する。
73
70
 
74
71
  ### 6.2. コマンドと正本参照
75
72
 
76
73
  - **判断基準**: `purpose` で呼び出し元から見た成功後の状態を示し、`reference` で正本の文書・設定キー・対象操作を特定する。通常は実行ファイルとサブコマンドを分け、`shell: false` とする。
77
- - **シェル起動の例外**: 管理された起動設定を呼び出し元が展開し、その起動契約がシェルを必要とする場合は `shell: true` を認める。シェルを必要とする理由、テンプレートの正本と管理境界、展開する値の検証・制限を確認できる参照先を示す。利用者入力を無制限にシェル構文として評価する契約は認めない。テンプレート全文や複数コマンドの処理手順は仕様へ転載しない。
74
+ - **シェル起動の例外**: 呼び出し元が管理された起動設定を展開し、シェルが必要な場合は `shell: true` を認める。理由、テンプレートの正本と管理境界、展開値の検証・制限の参照先を示す。利用者入力の無制限なシェル構文評価は認めない。テンプレート全文や複数コマンドの処理手順は転載しない。
78
75
  - **良い例**: AI provider CLI では `reference` に `.specdojo/exec-defaults.yaml` の `providers.<provider>.command_template` と exec 設定ガイドを示す。`shell: true` の理由を stdin から起動引数への変換として説明し、設定の保護と展開値の検証は同ガイドの契約を参照する。
79
76
  - **悪い例**: 実際はシェルを使うのに `false` と書く。「外部 CLI だから」という理由だけで `true` にする。`executable` に引数やパイプを連結し、起動設定と別のコマンド全文を管理する。
80
77
 
81
78
  ### 6.3. ストリーム
82
79
 
83
- - **判断基準**: stdin は渡す内容と入力終了の約束、stdout は呼び出し元が採用する範囲、stderr は診断の用途を記述する。stdin を使わない場合も要否と形式を明示する。出力内容の詳細構造は正本を参照し、呼び出し元の判定に必要な意味を残す。
84
- - **良い例**: テキストの進捗が混在する stdout では、末尾の構造化報告を抽出する範囲と、欠落・解析失敗時の扱いを示す。終了コードと報告内容の両方で完了を判断する契約なら、どちらが何を保証するかを書く。
80
+ - **判断基準**: stdin は入力内容と終端、stdout は採用範囲、stderr は診断用途を記す。stdin を使わない場合も要否と形式を明示する。出力の詳細構造は正本へ委ね、判定に必要な意味を残す。
81
+ - **良い例**: 進捗が混在する stdout では、末尾の構造化報告の抽出範囲と欠落・解析失敗時の扱いを示す。終了コードと報告内容の両方で完了を判断するなら、各々が保証する範囲を書く。
85
82
  - **悪い例**: 構造化部分があることを理由に stdout 全体を JSON と記す。「CLI の既定出力」とだけ書く。stderr が空なら成功と判定する。
86
83
 
87
84
  ### 6.4. ファイル
88
85
 
89
- - **判断基準**: 入力と出力を分け、パスの基準ディレクトリ、可変部分の解決方法(供給元と書式)、形式、作成・更新主体と読取主体、内容仕様の正本を特定する。これらは `description` など schema が許容する記入欄で説明し、専用キーや内容のフィールド一覧を追加しない。外部 CLI が作るファイルと呼び出し元が保存する実行記録を区別する。
90
- - **入出力がない場合**: `files` を記述する場合、CLI がファイルを作成しなければ `outputs: []`、入力ファイルがなければ `inputs: []` と明記する。ファイル入出力を一切行わない CLI では `files` キー自体を省略できる。
91
- - **良い例**: 入力ファイルについて作業ディレクトリからの相対パス、可変部分の解決元(確定済み取引の識別情報など)、作成主体(呼び出し元プロセス)、内容仕様の正本(schema やフォーマット仕様)を示す。CLI 自身が出力ファイルを作成しない場合は `outputs: []` と明記し、呼び出し元のログ保存と責務境界を分ける。
86
+ - **判断基準**: 入出力別に、パスの基準、可変部の供給元と書式、形式、作成・更新・読取主体、内容仕様の正本を特定する。`description` など既存欄で説明し、専用キーやフィールド一覧を追加しない。CLI の生成物と呼び出し元の実行記録を区別する。
87
+ - **入出力がない場合**: 入出力のない側の配列は `[]` または省略で表し、どちらも該当の入出力がないことを意味する。入出力が一切なければ `files` 自体を省略できる。未確認の場合と混同しない。
88
+ - **良い例**: 入力の相対パス、可変部分の解決元(確定済み取引の識別情報)、作成主体(呼び出し元)、内容仕様の正本を示す。CLI が出力ファイルを作らない例では `outputs: []` とし、呼び出し元のログ保存と分ける。
92
89
  - **悪い例**: 出力を「各種ファイル」とだけ書く。呼び出し元が保存するログや別段階で作成する result を、同じ CLI の出力として列挙する。入力ファイルの作成主体や可変部分の解決元が書かれていない。
93
90
 
94
91
  ### 6.5. 終了状態と識別条件
@@ -112,31 +109,22 @@ schema の後方互換性定義として残されている `arguments` の各項
112
109
 
113
110
  ### 6.8. 実行制約と失敗処置
114
111
 
115
- - **判断基準**: 作業ディレクトリと時間・並列実行・ネットワークの制約は公開契約や確認した実装・設定を根拠にする。設定から決まる上限を架空の固定値へ置き換えない。schema で参照値や上限なしを表せず判断が未了なら、許容されるプレースホルダと共通ラベルで draft に残し、現在動作・不足する判断・次の確認先を記録する。
112
+ - **判断基準**: 作業ディレクトリと時間・並列実行・ネットワークの制約は公開契約や確認した実装・設定を根拠にする。schema で参照値や上限なしを表せず判断が未了なら、許容されるプレースホルダと共通ラベルで現在動作・不足する判断・影響・確認先を残し、架空の固定値で埋めない。
116
113
  - **再試行と回復**: `retryable` と `retry.on_categories` を照合し、対象条件、試行上限の数え方、待機方式を揃える。利用制限でも短時間の制限と利用枠の枯渇を区別し、実際の停止・待機・切替条件は正本へ委ねる。タイムアウト時の子プロセスと部分出力、出力解析失敗時の既存変更、認証失敗時の確認先を個別に定める。
117
114
  - **良い例**: タイムアウトが未決定なら、現在は終了まで待つことと、上限・終了処置を決める必要を区別して記す。出力異常時は自動再試行を止め、変更を保持して人の確認または再開に委ねる。
118
115
  - **悪い例**: schema を通すためだけに時間や並列数を捏造する。「失敗時はリトライ」とだけ書く。認証・認可・入力不正を待機だけで回復する一時失敗として扱う。
119
116
 
120
117
  ### 6.9. 成果物の検証手順
121
118
 
122
- - **判断基準**: 作成・改訂した仕様 YAML を対象に、構造検証と契約内容の照合を分けて行う。schema の適用と modeline の共通規約は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] の「バリデーション」を正本とし、実行する検査は対象リポジトリの `package.json` と hook 設定に従う。
123
- - **対象と実行方法**: 以下の `<対象YAMLファイルのrepository相対パス>` を実際に変更した仕様のパスに置き換え、repository のルートで実行する。`validate:schema:file` script と Prettier がある場合に各コマンドを使い、別の検証環境では対応する schema を適用する同等の手順を確認する。
124
-
125
- ```bash
126
- npm run validate:schema:file -- --schema docs/specdojo/schemas/v1/ifx-cmd.schema.yaml --data '<対象YAMLファイルのrepository相対パス>'
127
- npx prettier --check '<対象YAMLファイルのrepository相対パス>'
128
- ```
129
-
130
- - **期待結果とエラー時対応**: schema 検証は対象パスに続く `: valid` と終了コード 0、整形確認は差分なしと終了コード 0 を確認する。エラー時は報告されたキー・型・メタ情報や整形差分を修正し、同じ対象で再実行する。
131
- - **契約内容の照合**: 構造検証では判定できない正本参照の実在・適用範囲、ファイルの作成主体・可変パス・内容仕様、終了判定と回復条件を照合する。DEV は起動・入出力・報告解析の検証入口、QE は正常・異常・再試行の期待結果、BA は業務完了と副作用を確認できるよう、参照先と結果を実行記録に残す。CLI 自体を起動する検証の詳細は参照先へ委ねる。
132
- - **良い例**: 変更した YAML と対応 schema を指定し、成功表示と終了コードを記録する。そのうえで、終了コードが同じ失敗の識別や再実行時の副作用を正本と照合する。
133
- - **悪い例**: schema のパスだけを示す。雛形の構造検証を省略したログを完成した仕様の検証成功とする。schema 合格だけで業務完了や再試行の安全性も保証したとみなす。
119
+ - **判断基準**: 作成・改訂した仕様 YAML の契約を、参照する正本と起動・入出力・報告解析の検証入口へ照合できること。CLI を起動する検証の詳細は参照先へ委ねる。
120
+ - **確認手順**: 正本の実在と適用範囲、ファイルの作成主体・可変パス・内容仕様を照合し、正常、同じコードの異なる失敗、出力欠落、途中失敗後の再実行を追う。入力・観測信号・期待結果と検証入口の参照先、確認結果を実行記録に残す。
121
+ - **合格条件**: 各ケースの業務完了判定、次の動作、副作用と回復条件が契約と一致する。識別不能な失敗は自動分類せず手動確認へつながり、未決事項は現在動作と影響をたどれること。不一致は仕様または参照先を修正し、該当ケースを再確認する。
122
+ - **良い例**: 同じ exit 1 を追加信号と判定順で分類し、途中失敗後の再実行で二重処理を防ぐ条件まで正本・検証結果と照合する。
123
+ - **悪い例**: schema 合格だけで業務完了や再試行の安全性も保証したとみなす。検証入口を示さず「動作確認済み」とする。
134
124
 
135
125
  ## 7. 禁止事項
136
126
 
137
- - 引数表、起動テンプレート全文、検出パターン一覧、schema の定義を正本と別に管理すること。
127
+ - 引数表、起動テンプレート全文、検出パターン一覧を正本と別に管理すること。
138
128
  - シェル起動の例外条件を満たさず `shell: true` とすること、または実際の起動方式を隠して `false` とすること。
139
- - 秘密値、秘密値を含む URL、個人の認証パスを本文・例・ログに含めること。
140
129
  - stdout / stderr、プロセス終了 / 業務完了、CLI の生成物 / 呼び出し元の記録を混同すること。
141
130
  - 追加信号のない終了コードだけで原因を断定したり、副作用の回復条件がないまま自動再試行したりすること。
142
- - 内部クラス名、プロセス起動ライブラリの API 呼び出し、スクリプト全文など、合意境界に不要な内部実装を記載すること。