specdojo 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (462) hide show
  1. package/.github/agents/specdojo-orchestrator.md +7 -3
  2. package/CHANGELOG.md +217 -0
  3. package/dist/catalog/build.js +24 -1
  4. package/dist/catalog/catalog.js +16 -14
  5. package/dist/catalog/plan.js +1 -1
  6. package/dist/catalog/scaffold.js +4 -1
  7. package/dist/commands/agent.js +5 -3
  8. package/dist/commands/build.js +69 -10
  9. package/dist/commands/git.js +206 -0
  10. package/dist/commands/init.js +9 -3
  11. package/dist/commands/night-orchestrator.js +6 -4
  12. package/dist/commands/where.js +25 -0
  13. package/dist/dashboard/dashboard-timeline.js +18 -16
  14. package/dist/dashboard/dashboard.js +616 -261
  15. package/dist/dashboard/epic-plan.js +81 -0
  16. package/dist/dashboard/exec-records.js +16 -20
  17. package/dist/dashboard/routines.js +11 -12
  18. package/dist/dashboard/timeline-build.js +5 -9
  19. package/dist/dashboard/timeline.js +23 -18
  20. package/dist/devcontainer/scaffold.js +18 -0
  21. package/dist/docs/frontmatter-namespace.js +1 -48
  22. package/dist/docs/index-command.js +2 -2
  23. package/dist/docs/yaml-business-tables.js +243 -0
  24. package/dist/docs/yaml-interface-tables.js +106 -0
  25. package/dist/docs/yaml-pages-command.js +5 -3
  26. package/dist/docs/yaml-pages.js +268 -3
  27. package/dist/docs/yaml-table-shared.js +70 -0
  28. package/dist/docs/yaml-tables.js +39 -0
  29. package/dist/exec/agent-config.js +31 -0
  30. package/dist/exec/agent-plan.js +3 -2
  31. package/dist/exec/agent-protected-config.js +2 -0
  32. package/dist/exec/commands.js +100 -39
  33. package/dist/exec/commit-hook-skips.js +78 -0
  34. package/dist/exec/core.js +19 -7
  35. package/dist/exec/events.js +179 -8
  36. package/dist/exec/evidence.js +77 -19
  37. package/dist/exec/handoff.js +9 -13
  38. package/dist/exec/limit.js +1 -1
  39. package/dist/exec/mechanical-result.js +45 -0
  40. package/dist/exec/migrate-records.js +249 -0
  41. package/dist/exec/parent-validation.js +209 -15
  42. package/dist/exec/pipeline-state.js +27 -5
  43. package/dist/exec/plans-condense-findings.js +89 -0
  44. package/dist/exec/plans-core.js +45 -19
  45. package/dist/exec/plans-generation.js +52 -30
  46. package/dist/exec/plans-grade-findings.js +8 -3
  47. package/dist/exec/plans-kata-findings.js +61 -0
  48. package/dist/exec/plans-planning.js +3 -3
  49. package/dist/exec/plans-storage.js +12 -24
  50. package/dist/exec/post-integration.js +162 -0
  51. package/dist/exec/queue-command.js +166 -0
  52. package/dist/exec/queue.js +285 -0
  53. package/dist/exec/register-foreign-wait.js +84 -0
  54. package/dist/exec/register-resume.js +55 -56
  55. package/dist/exec/register.js +26 -22
  56. package/dist/exec/repo-integration-sync.js +21 -5
  57. package/dist/exec/repo-integration.js +21 -1
  58. package/dist/exec/reporter.js +121 -23
  59. package/dist/exec/results.js +106 -25
  60. package/dist/exec/review-completion.js +47 -0
  61. package/dist/exec/review-kata.js +112 -0
  62. package/dist/exec/run/agent-pipeline.js +78 -8
  63. package/dist/exec/run/agent.js +32 -13
  64. package/dist/exec/run/change-scope.js +365 -0
  65. package/dist/exec/run/deferred-cleanup.js +31 -0
  66. package/dist/exec/run/in-place.js +73 -33
  67. package/dist/exec/run/job-lock.js +66 -0
  68. package/dist/exec/run/job-sequence.js +137 -0
  69. package/dist/exec/run/job.js +135 -41
  70. package/dist/exec/run/lifecycle-commands.js +189 -37
  71. package/dist/exec/run/lock.js +22 -1
  72. package/dist/exec/run/mode-shared.js +11 -3
  73. package/dist/exec/run/register-command.js +14 -15
  74. package/dist/exec/run/register-core.js +20 -13
  75. package/dist/exec/run/register-mode.js +77 -17
  76. package/dist/exec/run/register-post-review.js +21 -9
  77. package/dist/exec/run/register-resume.js +95 -31
  78. package/dist/exec/run/register-state.js +23 -15
  79. package/dist/exec/run/register-worktree.js +184 -139
  80. package/dist/exec/run/schedule-mode.js +79 -18
  81. package/dist/exec/run/schedule-prepare.js +204 -59
  82. package/dist/exec/run/schedule-task.js +203 -49
  83. package/dist/exec/run/shared.js +9 -3
  84. package/dist/exec/run/trailing-records.js +35 -0
  85. package/dist/exec/run-records.js +2 -0
  86. package/dist/exec/schedule/schedule.js +116 -4
  87. package/dist/exec/shared.js +1 -1
  88. package/dist/exec/smoke.js +190 -0
  89. package/dist/exec/strategy.js +14 -3
  90. package/dist/exec/task-view.js +6 -4
  91. package/dist/exec/trailing-records.js +242 -0
  92. package/dist/exec/trial-commands.js +8 -4
  93. package/dist/exec/trial-core.js +6 -1
  94. package/dist/exec/validate-records-commit.js +110 -0
  95. package/dist/exec/validate-records.js +148 -0
  96. package/dist/exec/validation-metrics.js +181 -0
  97. package/dist/exec/worktree-cleanup-lock.js +26 -0
  98. package/dist/exec/worktree-command.js +38 -17
  99. package/dist/exec/worktree-ops-commit.js +119 -48
  100. package/dist/exec/worktree-ops-lifecycle.js +77 -48
  101. package/dist/exec/worktree-ops-merge.js +13 -2
  102. package/dist/exec/worktree-ops.js +2 -2
  103. package/dist/exec/worktree.js +32 -4
  104. package/dist/grade/apply.js +32 -6
  105. package/dist/grade/command-apply.js +3 -3
  106. package/dist/grade/command-inspect.js +7 -5
  107. package/dist/grade/command-plan.js +1 -1
  108. package/dist/grade/command-run.js +7 -1
  109. package/dist/grade/command-shared.js +1 -1
  110. package/dist/grade/core.js +18 -5
  111. package/dist/grade/markdown.js +3 -3
  112. package/dist/grade/pipeline-state.js +15 -11
  113. package/dist/grade/plan.js +37 -17
  114. package/dist/grade/result.js +3 -3
  115. package/dist/grade/run.js +87 -11
  116. package/dist/grade/target-discovery.js +17 -4
  117. package/dist/grade/targets.js +12 -11
  118. package/dist/job/definition.js +84 -8
  119. package/dist/job/job.js +109 -39
  120. package/dist/job/noop.js +104 -0
  121. package/dist/register/authoring-sources.js +22 -16
  122. package/dist/register/core.js +2 -0
  123. package/dist/register/create-commands.js +28 -3
  124. package/dist/register/deliverable-target.js +9 -1
  125. package/dist/register/epic.js +104 -26
  126. package/dist/register/event-merge.js +3 -0
  127. package/dist/register/events.js +4 -0
  128. package/dist/register/external-project.js +3 -0
  129. package/dist/register/item.js +6 -0
  130. package/dist/register/maintenance-commands.js +6 -3
  131. package/dist/register/planning.js +7 -14
  132. package/dist/register/register.js +74 -16
  133. package/dist/register/track-domains.js +34 -0
  134. package/dist/register/track-plan.js +78 -0
  135. package/dist/register/transition-commands.js +8 -0
  136. package/dist/register/work-table.js +64 -0
  137. package/dist/review/grade.js +35 -13
  138. package/dist/routine/definition.js +13 -3
  139. package/dist/routine/failure.js +30 -0
  140. package/dist/routine/routine.js +189 -71
  141. package/dist/routine/status.js +62 -0
  142. package/dist/routine/storage.js +33 -0
  143. package/dist/schedule/schedule.js +39 -39
  144. package/dist/schedule/strategy-generate-document.js +26 -14
  145. package/dist/schedule/strategy-generate-scope.js +17 -45
  146. package/dist/schedule/strategy-generate.js +33 -3
  147. package/dist/schedule/strategy-profiles.js +86 -12
  148. package/dist/shared/agent-types.js +7 -0
  149. package/dist/shared/condense-records.js +25 -0
  150. package/dist/shared/cross-process-lock.js +9 -1
  151. package/dist/shared/deprecation.js +8 -0
  152. package/dist/shared/dist-freshness.js +8 -2
  153. package/dist/shared/document-metadata.js +20 -0
  154. package/dist/shared/finding-cause.js +20 -0
  155. package/dist/shared/frontmatter-namespace.js +48 -0
  156. package/dist/shared/git-environment.js +2 -1
  157. package/dist/shared/git.js +186 -16
  158. package/dist/shared/grade-result.js +17 -1
  159. package/dist/shared/lefthook-scaffold.js +3 -0
  160. package/dist/shared/local-config.js +244 -0
  161. package/dist/shared/local-state.js +20 -0
  162. package/dist/shared/markdownlint-config.js +8 -3
  163. package/dist/shared/plan-conventions.js +129 -0
  164. package/dist/shared/plan-templates.js +57 -41
  165. package/dist/shared/run-records.js +224 -0
  166. package/dist/shared/specdojo-config.js +73 -41
  167. package/dist/shared/specdojo-gitignore.js +1 -0
  168. package/dist/shared/text.js +74 -6
  169. package/dist/shared/timeline-index.js +2 -0
  170. package/dist/shared/where-alias.js +13 -0
  171. package/dist/specdojo.js +4 -0
  172. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +11 -2
  173. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +4 -74
  174. package/docs/ja/specdojo/exec-templates/xep-condense-template.md +50 -0
  175. package/docs/ja/specdojo/exec-templates/xep-draft-template.md +17 -5
  176. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +16 -3
  177. package/docs/ja/specdojo/exec-templates/xep-recipe-guided-template.md +15 -5
  178. package/docs/ja/specdojo/exec-templates/xep-recipe-maintenance-template.md +6 -0
  179. package/docs/ja/specdojo/exec-templates/xep-register-template.md +1 -1
  180. package/docs/ja/specdojo/exec-templates/xep-rulebook-maintenance-template.md +6 -0
  181. package/docs/ja/specdojo/exec-templates/xep-sample-maintenance-template.md +6 -0
  182. package/docs/ja/specdojo/exec-templates/xep-template-maintenance-template.md +6 -0
  183. package/docs/ja/specdojo/exec-templates/xer-condense-template.md +25 -0
  184. package/docs/ja/specdojo/exec-templates/xp-common-conventions-template.md +50 -0
  185. package/docs/ja/specdojo/exec-templates/xrp-common-conventions-template.md +30 -0
  186. package/docs/ja/specdojo/guides/branch-workflow-guide.md +1 -1
  187. package/docs/ja/specdojo/guides/docs-editing-guide.md +12 -0
  188. package/docs/ja/specdojo/guides/docs-structure-guide.md +48 -15
  189. package/docs/ja/specdojo/guides/exec-config-guide.md +69 -19
  190. package/docs/ja/specdojo/guides/exec-operation-guide.md +97 -18
  191. package/docs/ja/specdojo/guides/exec-worktree-guide.md +20 -11
  192. package/docs/ja/specdojo/guides/job-sequence-guide.md +77 -0
  193. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +92 -55
  194. package/docs/ja/specdojo/guides/project-move-guide.md +381 -0
  195. package/docs/ja/specdojo/guides/quick-start-guide.md +73 -17
  196. package/docs/ja/specdojo/guides/register-operation-guide.md +26 -6
  197. package/docs/ja/specdojo/guides/remote-host-development-guide.md +2 -0
  198. package/docs/ja/specdojo/guides/review-guide.md +22 -19
  199. package/docs/ja/specdojo/guides/routine-operation-guide.md +23 -12
  200. package/docs/ja/specdojo/guides/ryu-guide.md +23 -13
  201. package/docs/ja/specdojo/guides/schedule-design-guide.md +27 -21
  202. package/docs/ja/specdojo/guides/schedule-operation-guide.md +27 -3
  203. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +5 -4
  204. package/docs/ja/specdojo/guides/timeline-design-guide.md +27 -144
  205. package/docs/ja/specdojo/guides/use-case-guide.md +92 -155
  206. package/docs/ja/specdojo/guides/waza-guide.md +12 -8
  207. package/docs/ja/specdojo/recipes/bac-recipe.md +111 -0
  208. package/docs/ja/specdojo/recipes/bes-recipe.md +141 -0
  209. package/docs/ja/specdojo/recipes/bps-recipe.md +88 -139
  210. package/docs/ja/specdojo/recipes/br-recipe.md +77 -0
  211. package/docs/ja/specdojo/recipes/cdfd-overview-recipe.md +97 -109
  212. package/docs/ja/specdojo/recipes/cdfd-recipe.md +85 -146
  213. package/docs/ja/specdojo/recipes/cdfd-uc-recipe.md +92 -99
  214. package/docs/ja/specdojo/recipes/cnd-recipe.md +135 -0
  215. package/docs/ja/specdojo/recipes/cpd-recipe.md +140 -0
  216. package/docs/ja/specdojo/recipes/cxd-recipe.md +162 -0
  217. package/docs/ja/specdojo/recipes/ifd-recipe.md +145 -0
  218. package/docs/ja/specdojo/recipes/ifx-cmd-recipe.md +112 -90
  219. package/docs/ja/specdojo/recipes/ifx-index-recipe.md +164 -0
  220. package/docs/ja/specdojo/recipes/pm-communication-plan-recipe.md +60 -49
  221. package/docs/ja/specdojo/recipes/pm-members-recipe.md +50 -51
  222. package/docs/ja/specdojo/recipes/pm-organization-recipe.md +59 -48
  223. package/docs/ja/specdojo/recipes/pm-plan-recipe.md +72 -50
  224. package/docs/ja/specdojo/recipes/pm-quality-management-plan-recipe.md +40 -49
  225. package/docs/ja/specdojo/recipes/pm-raci-recipe.md +42 -48
  226. package/docs/ja/specdojo/recipes/pm-roles-recipe.md +52 -81
  227. package/docs/ja/specdojo/recipes/prj-assumptions-constraints-dependencies-recipe.md +64 -91
  228. package/docs/ja/specdojo/recipes/prj-charter-recipe.md +71 -106
  229. package/docs/ja/specdojo/recipes/prj-comparison-of-alternatives-recipe.md +78 -156
  230. package/docs/ja/specdojo/recipes/prj-issues-and-approach-recipe.md +62 -111
  231. package/docs/ja/specdojo/recipes/prj-scope-recipe.md +67 -123
  232. package/docs/ja/specdojo/recipes/prj-stakeholder-register-recipe.md +60 -96
  233. package/docs/ja/specdojo/recipes/prj-success-criteria-and-acceptance-criteria-recipe.md +61 -105
  234. package/docs/ja/specdojo/recipes/stsd-recipe.md +88 -80
  235. package/docs/ja/specdojo/recipes/sysd-critical-flows-recipe.md +129 -0
  236. package/docs/ja/specdojo/recipes/sysd-cross-cutting-policy-recipe.md +146 -0
  237. package/docs/ja/specdojo/recipes/sysd-index-recipe.md +141 -0
  238. package/docs/ja/specdojo/recipes/tsd-recipe.md +149 -129
  239. package/docs/ja/specdojo/references/command-reference.md +303 -148
  240. package/docs/ja/specdojo/references/deliverables-reference.md +30 -16
  241. package/docs/ja/specdojo/references/directory-layout-reference.md +3 -2
  242. package/docs/ja/specdojo/references/specdojo-config-reference.md +54 -18
  243. package/docs/ja/specdojo/rulebooks/atc-index-rulebook.md +101 -257
  244. package/docs/ja/specdojo/rulebooks/atc-rulebook.md +102 -228
  245. package/docs/ja/specdojo/rulebooks/bac-rulebook.md +63 -290
  246. package/docs/ja/specdojo/rulebooks/bdd-rulebook.md +162 -80
  247. package/docs/ja/specdojo/rulebooks/bds-rulebook.md +118 -155
  248. package/docs/ja/specdojo/rulebooks/bes-index-rulebook.md +128 -60
  249. package/docs/ja/specdojo/rulebooks/bes-rulebook.md +70 -94
  250. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +24 -56
  251. package/docs/ja/specdojo/rulebooks/br-rulebook.md +58 -103
  252. package/docs/ja/specdojo/rulebooks/ccd-mermaid-rulebook.md +103 -223
  253. package/docs/ja/specdojo/rulebooks/cdfd-d2-rulebook.md +18 -93
  254. package/docs/ja/specdojo/rulebooks/cdfd-mermaid-rulebook.md +18 -52
  255. package/docs/ja/specdojo/rulebooks/cdfd-overview-rulebook.md +109 -147
  256. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +80 -108
  257. package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +51 -55
  258. package/docs/ja/specdojo/rulebooks/cdr-rulebook.md +144 -0
  259. package/docs/ja/specdojo/rulebooks/cdsd-rulebook.md +81 -68
  260. package/docs/ja/specdojo/rulebooks/cdt-rulebook.md +139 -0
  261. package/docs/ja/specdojo/rulebooks/cld-rulebook.md +9 -184
  262. package/docs/ja/specdojo/rulebooks/clis-rulebook.md +170 -0
  263. package/docs/ja/specdojo/rulebooks/cnd-mermaid-rulebook.md +33 -86
  264. package/docs/ja/specdojo/rulebooks/cnd-rulebook.md +79 -249
  265. package/docs/ja/specdojo/rulebooks/cop-index-rulebook.md +45 -131
  266. package/docs/ja/specdojo/rulebooks/cop-rulebook.md +69 -275
  267. package/docs/ja/specdojo/rulebooks/cpd-mermaid-rulebook.md +20 -112
  268. package/docs/ja/specdojo/rulebooks/cpd-rulebook.md +79 -249
  269. package/docs/ja/specdojo/rulebooks/cxd-mermaid-rulebook.md +12 -145
  270. package/docs/ja/specdojo/rulebooks/cxd-rulebook.md +115 -256
  271. package/docs/ja/specdojo/rulebooks/dct-index-rulebook.md +79 -109
  272. package/docs/ja/specdojo/rulebooks/dct-rulebook.md +119 -174
  273. package/docs/ja/specdojo/rulebooks/dec-rulebook.md +6 -14
  274. package/docs/ja/specdojo/rulebooks/dmd-index-rulebook.md +22 -66
  275. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +36 -94
  276. package/docs/ja/specdojo/rulebooks/dss-rulebook.md +171 -0
  277. package/docs/ja/specdojo/rulebooks/etc-index-rulebook.md +31 -131
  278. package/docs/ja/specdojo/rulebooks/etc-rulebook.md +50 -104
  279. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +93 -57
  280. package/docs/ja/specdojo/rulebooks/ifd-mermaid-rulebook.md +63 -253
  281. package/docs/ja/specdojo/rulebooks/ifx-api-rulebook.md +14 -20
  282. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +79 -76
  283. package/docs/ja/specdojo/rulebooks/ifx-file-rulebook.md +182 -237
  284. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +111 -40
  285. package/docs/ja/specdojo/rulebooks/ifx-msg-rulebook.md +14 -22
  286. package/docs/ja/specdojo/rulebooks/imp-business-rulebook.md +23 -46
  287. package/docs/ja/specdojo/rulebooks/imp-data-rulebook.md +41 -64
  288. package/docs/ja/specdojo/rulebooks/imp-interface-rulebook.md +16 -40
  289. package/docs/ja/specdojo/rulebooks/imp-operations-rulebook.md +34 -61
  290. package/docs/ja/specdojo/rulebooks/imp-test-rulebook.md +27 -50
  291. package/docs/ja/specdojo/rulebooks/itc-index-rulebook.md +70 -199
  292. package/docs/ja/specdojo/rulebooks/itc-rulebook.md +65 -153
  293. package/docs/ja/specdojo/rulebooks/mip-index-rulebook.md +74 -150
  294. package/docs/ja/specdojo/rulebooks/mm-rulebook.md +12 -23
  295. package/docs/ja/specdojo/rulebooks/mtp-rulebook.md +99 -176
  296. package/docs/ja/specdojo/rulebooks/nfr-availability-rulebook.md +35 -61
  297. package/docs/ja/specdojo/rulebooks/nfr-index-rulebook.md +75 -117
  298. package/docs/ja/specdojo/rulebooks/nfr-integrity-rulebook.md +31 -60
  299. package/docs/ja/specdojo/rulebooks/nfr-maintainability-rulebook.md +26 -81
  300. package/docs/ja/specdojo/rulebooks/nfr-operations-rulebook.md +32 -70
  301. package/docs/ja/specdojo/rulebooks/nfr-performance-rulebook.md +45 -87
  302. package/docs/ja/specdojo/rulebooks/nfr-reliability-rulebook.md +48 -101
  303. package/docs/ja/specdojo/rulebooks/nfr-security-safety-rulebook.md +44 -80
  304. package/docs/ja/specdojo/rulebooks/nfr-usability-rulebook.md +59 -127
  305. package/docs/ja/specdojo/rulebooks/opd-index-rulebook.md +31 -50
  306. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +42 -109
  307. package/docs/ja/specdojo/rulebooks/opr-index-rulebook.md +29 -42
  308. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +29 -87
  309. package/docs/ja/specdojo/rulebooks/otp-index-rulebook.md +62 -84
  310. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +11 -61
  311. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +92 -102
  312. package/docs/ja/specdojo/rulebooks/pm-change-request-log-rulebook.md +25 -34
  313. package/docs/ja/specdojo/rulebooks/pm-communication-plan-rulebook.md +30 -53
  314. package/docs/ja/specdojo/rulebooks/pm-issue-log-rulebook.md +23 -35
  315. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +27 -45
  316. package/docs/ja/specdojo/rulebooks/pm-organization-rulebook.md +45 -59
  317. package/docs/ja/specdojo/rulebooks/pm-plan-rulebook.md +56 -66
  318. package/docs/ja/specdojo/rulebooks/pm-quality-management-plan-rulebook.md +54 -62
  319. package/docs/ja/specdojo/rulebooks/pm-raci-rulebook.md +46 -65
  320. package/docs/ja/specdojo/rulebooks/pm-risk-register-rulebook.md +28 -35
  321. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +65 -97
  322. package/docs/ja/specdojo/rulebooks/pr-rulebook.md +6 -18
  323. package/docs/ja/specdojo/rulebooks/prj-assumptions-constraints-dependencies-rulebook.md +48 -78
  324. package/docs/ja/specdojo/rulebooks/prj-charter-rulebook.md +23 -97
  325. package/docs/ja/specdojo/rulebooks/prj-comparison-of-alternatives-rulebook.md +61 -153
  326. package/docs/ja/specdojo/rulebooks/prj-issues-and-approach-rulebook.md +43 -116
  327. package/docs/ja/specdojo/rulebooks/prj-scope-rulebook.md +16 -51
  328. package/docs/ja/specdojo/rulebooks/prj-stakeholder-register-rulebook.md +47 -92
  329. package/docs/ja/specdojo/rulebooks/prj-success-criteria-and-acceptance-criteria-rulebook.md +25 -84
  330. package/docs/ja/specdojo/rulebooks/sac-rulebook.md +44 -107
  331. package/docs/ja/specdojo/rulebooks/sf-index-rulebook.md +106 -32
  332. package/docs/ja/specdojo/rulebooks/sf-rulebook.md +111 -61
  333. package/docs/ja/specdojo/rulebooks/sld-rulebook.md +129 -59
  334. package/docs/ja/specdojo/rulebooks/stc-index-rulebook.md +90 -189
  335. package/docs/ja/specdojo/rulebooks/stc-rulebook.md +45 -105
  336. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +46 -40
  337. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +104 -68
  338. package/docs/ja/specdojo/rulebooks/sysd-critical-flows-rulebook.md +64 -330
  339. package/docs/ja/specdojo/rulebooks/sysd-cross-cutting-policy-rulebook.md +70 -263
  340. package/docs/ja/specdojo/rulebooks/sysd-index-rulebook.md +58 -200
  341. package/docs/ja/specdojo/rulebooks/sysd-rulebook.md +47 -60
  342. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +4 -9
  343. package/docs/ja/specdojo/rulebooks/trc-requirements-to-specs-rulebook.md +69 -71
  344. package/docs/ja/specdojo/rulebooks/trc-requirements-to-tests-rulebook.md +65 -72
  345. package/docs/ja/specdojo/rulebooks/tsd-index-rulebook.md +35 -46
  346. package/docs/ja/specdojo/rulebooks/tsd-rulebook.md +49 -66
  347. package/docs/ja/specdojo/rulebooks/tsp-index-rulebook.md +64 -139
  348. package/docs/ja/specdojo/rulebooks/uis-rulebook.md +91 -161
  349. package/docs/ja/specdojo/rulebooks/utc-index-rulebook.md +49 -144
  350. package/docs/ja/specdojo/rulebooks/utc-rulebook.md +67 -155
  351. package/docs/ja/specdojo/samples/bac-sample.md +106 -21
  352. package/docs/ja/specdojo/samples/bdd-sample.yaml +143 -35
  353. package/docs/ja/specdojo/samples/bds-sample.md +87 -21
  354. package/docs/ja/specdojo/samples/bes-index-sample.md +42 -20
  355. package/docs/ja/specdojo/samples/bes-sample.md +70 -21
  356. package/docs/ja/specdojo/samples/bps-sample.md +42 -54
  357. package/docs/ja/specdojo/samples/br-sample.md +57 -15
  358. package/docs/ja/specdojo/samples/ccd-sample.md +80 -19
  359. package/docs/ja/specdojo/samples/cdfd-sample.md +172 -99
  360. package/docs/ja/specdojo/samples/cdfd-uc-sample.md +9 -7
  361. package/docs/ja/specdojo/samples/cdr-sample.md +78 -0
  362. package/docs/ja/specdojo/samples/cdsd-sample.md +73 -20
  363. package/docs/ja/specdojo/samples/cdt-sample.md +116 -0
  364. package/docs/ja/specdojo/samples/cld-sample.md +3 -30
  365. package/docs/ja/specdojo/samples/clis-sample.md +125 -0
  366. package/docs/ja/specdojo/samples/cnd-sample.md +127 -21
  367. package/docs/ja/specdojo/samples/cpd-sample.md +136 -22
  368. package/docs/ja/specdojo/samples/cxd-sample.md +108 -22
  369. package/docs/ja/specdojo/samples/dct-index-sample.yaml +63 -17
  370. package/docs/ja/specdojo/samples/dec-sample.md +2 -3
  371. package/docs/ja/specdojo/samples/dss-sample.md +175 -0
  372. package/docs/ja/specdojo/samples/gl-sample.yaml +50 -14
  373. package/docs/ja/specdojo/samples/ifd-sample.md +105 -21
  374. package/docs/ja/specdojo/samples/ifx-api-sample.yaml +0 -2
  375. package/docs/ja/specdojo/samples/ifx-cmd-sample.yaml +91 -60
  376. package/docs/ja/specdojo/samples/ifx-file-sample.md +462 -21
  377. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +87 -19
  378. package/docs/ja/specdojo/samples/ifx-msg-sample.yaml +0 -2
  379. package/docs/ja/specdojo/samples/job-sequence.yaml +67 -0
  380. package/docs/ja/specdojo/samples/mip-index-sample.md +98 -20
  381. package/docs/ja/specdojo/samples/pm-communication-plan-sample.md +26 -19
  382. package/docs/ja/specdojo/samples/pm-members-sample.yaml +37 -13
  383. package/docs/ja/specdojo/samples/pm-organization-sample.md +42 -21
  384. package/docs/ja/specdojo/samples/pm-plan-sample.md +78 -26
  385. package/docs/ja/specdojo/samples/pm-quality-management-plan-sample.md +41 -22
  386. package/docs/ja/specdojo/samples/pm-raci-sample.md +63 -28
  387. package/docs/ja/specdojo/samples/pm-roles-sample.yaml +13 -12
  388. package/docs/ja/specdojo/samples/prj-assumptions-constraints-dependencies-sample.md +33 -25
  389. package/docs/ja/specdojo/samples/prj-charter-sample.md +42 -59
  390. package/docs/ja/specdojo/samples/prj-comparison-of-alternatives-sample.md +83 -62
  391. package/docs/ja/specdojo/samples/prj-success-criteria-and-acceptance-criteria-sample.md +30 -33
  392. package/docs/ja/specdojo/samples/sf-index-sample.md +47 -20
  393. package/docs/ja/specdojo/samples/sf-sample.md +109 -21
  394. package/docs/ja/specdojo/samples/sld-sample.md +88 -21
  395. package/docs/ja/specdojo/samples/stsd-sample.md +54 -26
  396. package/docs/ja/specdojo/samples/sysd-critical-flows-sample.md +166 -21
  397. package/docs/ja/specdojo/samples/sysd-cross-cutting-policy-sample.md +178 -21
  398. package/docs/ja/specdojo/samples/sysd-index-sample.md +82 -21
  399. package/docs/ja/specdojo/samples/tml-sample.yaml +4 -1
  400. package/docs/ja/specdojo/samples/uis-sample.md +141 -20
  401. package/docs/ja/specdojo/standards/document-metadata-standard.md +33 -4
  402. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +3 -1
  403. package/docs/ja/specdojo/standards/job-definition-standard.md +24 -9
  404. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +1 -0
  405. package/docs/ja/specdojo/templates/bac-template.md +76 -0
  406. package/docs/ja/specdojo/templates/bes-template.md +56 -0
  407. package/docs/ja/specdojo/templates/br-template.md +64 -0
  408. package/docs/ja/specdojo/templates/cdfd-template.md +81 -54
  409. package/docs/ja/specdojo/templates/cdfd-uc-template.md +9 -5
  410. package/docs/ja/specdojo/templates/cdr-template.md +58 -0
  411. package/docs/ja/specdojo/templates/cnd-template.md +137 -0
  412. package/docs/ja/specdojo/templates/cpd-template.md +129 -0
  413. package/docs/ja/specdojo/templates/cxd-template.md +105 -0
  414. package/docs/ja/specdojo/templates/dct-data-model-cdt-template.yaml +40 -0
  415. package/docs/ja/specdojo/templates/dct-data-model-cld-template.yaml +7 -14
  416. package/docs/ja/specdojo/templates/dct-index-template.md +9 -20
  417. package/docs/ja/specdojo/templates/dct-project-management-template.yaml +5 -1
  418. package/docs/ja/specdojo/templates/ifd-template.md +86 -0
  419. package/docs/ja/specdojo/templates/ifx-cmd-template.yaml +44 -28
  420. package/docs/ja/specdojo/templates/ifx-index-template.yaml +40 -0
  421. package/docs/ja/specdojo/templates/opr-template.md +2 -4
  422. package/docs/ja/specdojo/templates/pm-organization-template.md +9 -3
  423. package/docs/ja/specdojo/templates/pm-plan-template.md +4 -4
  424. package/docs/ja/specdojo/templates/pm-quality-management-plan-template.md +17 -9
  425. package/docs/ja/specdojo/templates/pm-raci-template.md +24 -13
  426. package/docs/ja/specdojo/templates/pm-roles-template.yaml +3 -2
  427. package/docs/ja/specdojo/templates/prj-assumptions-constraints-dependencies-template.md +6 -3
  428. package/docs/ja/specdojo/templates/prj-comparison-of-alternatives-template.md +22 -19
  429. package/docs/ja/specdojo/templates/stsd-template.md +46 -21
  430. package/docs/ja/specdojo/templates/sysd-critical-flows-template.md +94 -0
  431. package/docs/ja/specdojo/templates/sysd-cross-cutting-policy-template.md +122 -0
  432. package/docs/ja/specdojo/templates/sysd-index-template.md +89 -0
  433. package/docs/specdojo/lib/yaml-metadata.cjs +7 -0
  434. package/docs/specdojo/schemas/v1/bdd.schema.yaml +25 -57
  435. package/docs/specdojo/schemas/v1/condense-records.schema.yaml +26 -0
  436. package/docs/specdojo/schemas/v1/dct.schema.yaml +10 -0
  437. package/docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml +3 -0
  438. package/docs/specdojo/schemas/v1/esil.schema.yaml +7 -141
  439. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +5 -1
  440. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +95 -8
  441. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +38 -0
  442. package/docs/specdojo/schemas/v1/exec-plan-frontmatter.schema.yaml +14 -0
  443. package/docs/specdojo/schemas/v1/exec-result-frontmatter.schema.yaml +18 -0
  444. package/docs/specdojo/schemas/v1/finding-cause.schema.yaml +22 -0
  445. package/docs/specdojo/schemas/v1/grade-pipeline-state.schema.yaml +1 -1
  446. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +2 -0
  447. package/docs/specdojo/schemas/v1/ifx-cmd.schema.yaml +65 -5
  448. package/docs/specdojo/schemas/v1/ifx-index.schema.yaml +142 -0
  449. package/docs/specdojo/schemas/v1/job-run.schema.yaml +23 -0
  450. package/docs/specdojo/schemas/v1/job.schema.yaml +63 -2
  451. package/docs/specdojo/schemas/v1/register-events.schema.yaml +2 -0
  452. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +17 -1
  453. package/docs/specdojo/schemas/v1/sch-strategy.schema.yaml +2 -2
  454. package/package.json +10 -7
  455. package/templates/antigravity/orchestrator.md +7 -3
  456. package/templates/claude/agents/specdojo-orchestrator.md +7 -3
  457. package/templates/codex/agents/specdojo-orchestrator.toml +7 -3
  458. package/templates/codex/orchestrator.md +7 -3
  459. package/templates/devcontainer/tmux.conf +6 -0
  460. package/templates/init-exec-defaults.yaml +13 -0
  461. package/templates/lefthook/tools/specdojo-pre-commit.mjs +8 -0
  462. package/templates/opencode/agents/specdojo-orchestrator.md +8 -4
@@ -6,7 +6,7 @@ specdojo:
6
6
  deliverable_type: glossary
7
7
  status: draft
8
8
  target_format: yaml
9
- recipe: undecided
9
+ recipe: not-needed
10
10
  sample: specdojo:gl-sample
11
11
  template: not-needed
12
12
  based_on:
@@ -17,95 +17,131 @@ specdojo:
17
17
 
18
18
  Glossary Documentation Rules
19
19
 
20
- 本ドキュメントは、業務分析・要求定義・設計・テストで参照する **用語集(Glossary)を YAML 形式で記述する標準ルール**です。
20
+ 業務分析・要求定義・設計・テストで使う概念の意味と境界を YAML で定めます。
21
21
 
22
22
  ## 1. 全体方針
23
23
 
24
- - 用語集は YAML 形式で記述し、プロジェクト内で同じ言葉を同じ意味で使うための「辞書」として機能する。
25
- - 業務データ辞書(BDD)やビジネスルール(BR)などで参照する用語は、先に用語集に登録して **用語ID(`tm-...`)を固定**し、用語集をその正式な参照先(正)とする。
26
- - 用語は **業務用語(日本語)**で記述し、UI文言や内部コード名の辞書化は必要最小限にする。
27
- - プロジェクト固有の用語集はプロジェクトごとに作成・保守し、実データは対象プロジェクトの文書内に記述する。
24
+ - 業務の概念と、利用者が扱う操作・状態・役割を収録する。
25
+ - 定義は `locale` の言語で書く。英語名・コマンド名・固有名詞は併記可。翻訳版は別ファイルにする。
26
+ - 横断の概念は `gl-common`(対象付きなら `gl-<対象>-common`)へ集める。翻訳版を除き、同じ概念を複数の用語集に定義しない。
27
+ - **共通の運用**: 役割は適用先のメンバー定義、`status` の昇格・承認、改訂と廃止、未決事項の引き継ぎは [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従う。整形・lint はリポジトリの検証で扱い、業務の検証に含めない。
28
28
 
29
- ## 2. 位置づけと用語定義
29
+ ## 2. 位置づけ
30
30
 
31
- - 本用語集(Glossary)は、プロジェクト全体の SSOT(Single Source of Truth)としての役割を持つ。
32
- - 各種設計ドキュメントの `glossaryTermId` 等は、すべて本ルールで採番された `tm-...` ID を参照する。
31
+ - 意味の正本とし、判定条件・データ項目・操作手順・実装詳細は各仕様・設計へ委ねる。
32
+ - 冒頭のコメントまたは代表用語の注記で、対象範囲と共通・他領域の正本を示す。
33
+ - 配置は [[specdojo:docs-structure-guide|ドキュメント構成ガイド]] に従う。
33
34
 
34
35
  ## 3. ファイル命名・ID規則
35
36
 
36
37
  ### 3.1. ファイル命名
37
38
 
38
- - ファイル名: `gl-<対象領域>-<locale>.yaml`
39
- - 例: `gl-sales-ja.yaml`, `gl-inventory-ja.yaml`
40
- - 多言語化する場合はファイルを分け、1 つのファイル内で言語を混在させない。
39
+ - 基本は `gl-<対象領域>.yaml`(例: `gl-sales.yaml`)。
40
+ - 翻訳版の併置は `gl-<対象領域>-<locale>.yaml` とし、用語集 ID も区別する。
41
+ - 同梱の完成例は `gl-sample.yaml` とする。
41
42
 
42
43
  ### 3.2. ID規約
43
44
 
44
- - 用語集ID: `^gl-[a-z0-9-]+$` の形式とする。
45
- - 用語ID: `^tm-[a-z0-9-]+$` の形式とする。
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 を示す。
46
49
 
47
50
  ## 4. 推奨 Frontmatter 項目
48
51
 
49
- YAML ファイルの先頭に、以下のメタデータ(ルートキー)を持たせることを推奨する。
52
+ メタ情報はルートに置く。下記 schema を正本とし、先頭の modeline に相対パスで指定する。
50
53
 
51
- | 項目 | 説明 | 必須 |
52
- | -------- | ---------------------------------- | ---- |
53
- | id | 用語集ID(`gl-...`) | ○ |
54
- | type | `glossary` 固定 | ○ |
55
- | rulebook | `specdojo:gl-rulebook` | ○ |
56
- | title | 用語集名(例: 用語集: 在庫・調達) | ○ |
57
- | locale | 言語(例: `ja` / `en`) | ○ |
58
- | status | `draft` / `ready` / `deprecated` | 任意 |
54
+ | 項目 | 説明 | 必須 |
55
+ | ---------- | -------------------------------------------- | ---- |
56
+ | `id` | 「ID規約」に従う用語集 ID | ○ |
57
+ | `type` | `glossary` 固定 | ○ |
58
+ | `rulebook` | `specdojo:gl-rulebook` | ○ |
59
+ | `title` | 対象領域を示す用語集名 | ○ |
60
+ | `locale` | 定義の言語(例: `ja` / `en`) | ○ |
61
+ | `status` | 文書成熟度。`draft` / `ready` / `deprecated` | ○ |
62
+
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=<相対パス>`。
59
64
 
60
65
  ## 5. 本文要件
61
66
 
62
67
  ### 5.1. ルートキー要件
63
68
 
64
- - メタデータに加え、トップレベルに `terms`(配列)を必ず持つ。
69
+ - ルートの `terms` は必須の用語オブジェクト配列とする。
70
+ - 分類や参照先の概念にも定義を持たせる。
71
+ - schema にないキーは追加しない。
65
72
 
66
73
  ### 5.2. `terms` の項目
67
74
 
68
- 各用語の要素は以下のキーを持つ。
69
-
70
- | 項目 | 説明 | 必須 |
71
- | ------------ | --------------------------------------------------------- | ---- |
72
- | id | 用語ID(`tm-...`) | ○ |
73
- | term | 用語(正式名称) | ○ |
74
- | englishName | 英語名(概念の英語表記) | 任意 |
75
- | aliases | 別名(配列) | 任意 |
76
- | definition | 定義(境界が分かる説明) | ○ |
77
- | notes | 補足・運用メモ(前提、例外、使って良い文脈/ダメな文脈等) | 任意 |
78
- | category | 分類(推奨: 分類用の用語ID、例: `tm-inventory`) | 任意 |
79
- | relatedTerms | 関連用語ID(配列) | 任意 |
80
- | source | 出典/参考(URL等) | 任意 |
81
- | status | `official` / `deprecated` / `candidate` など | 任意 |
82
- | example | 用例(短い例文) | 任意 |
75
+ | 項目 | 説明 | 必須 |
76
+ | -------------- | ------------------------------------------------------- | ---- |
77
+ | `id` | 安定した用語 ID | ○ |
78
+ | `term` | 利用者が目にする正式な呼び方 | ○ |
79
+ | `englishName` | 概念の英語名 | 任意 |
80
+ | `aliases` | 同じ概念の別名・従来表記の配列 | 任意 |
81
+ | `definition` | 意味と他の概念との境界が分かる定義 | ○ |
82
+ | `notes` | 読み手向けの前提・例外・使用文脈 | 任意 |
83
+ | `category` | 同じ用語集内で分類に使う用語 ID | 任意 |
84
+ | `relatedTerms` | 同じ用語集内の関連用語 ID の配列 | 任意 |
85
+ | `source` | 文書リンク・schema のパスと定義名・URL | 任意 |
86
+ | `status` | 用語の採用状態。`official` / `deprecated` / `candidate` | 任意 |
87
+ | `example` | 用語を使う短い例文 | 任意 |
88
+
89
+ 任意項目は必要なものだけ記載し、用語の `status` と文書成熟度を区別する。`candidate` は業務の利用者・確認者と用例・根拠を照合し、意味・境界・呼び方の合意後に `official` にする。未合意なら候補に留め、`notes` に論点と利用への影響を示す。
83
90
 
84
91
  ## 6. 記述ガイド
85
92
 
86
- ### 6.1. IDの命名推奨
93
+ ### 6.1. 全体方針・位置づけの判断
94
+
95
+ - 良い例: 「商品」は共通、「つけ残高」は販売へ置く。
96
+ - 悪い例: 販売と在庫で同じ「商品」を別々に定義する。
97
+
98
+ ### 6.2. ファイル命名・ID の判断
99
+
100
+ 新規 ID は名詞を基本とし、難解な略語は避ける。
101
+
102
+ - 良い例: 新規は `tm-sales-credit-limit`、既存の `tm-accounts-receivable` は維持する。
103
+ - 悪い例: 領域ごとに `tm-status` を新設する、整形で確定 ID を改名する。
104
+
105
+ ### 6.3. メタ情報・ルート構造の判断
106
+
107
+ - 良い例: `title: 用語集(販売)`、`locale: ja` とルートの `terms`。
108
+ - 悪い例: `specdojo:` で全体を包む、`terms` を文章で代用する。
109
+
110
+ ### 6.4. 用語の見出し・英語名の判断
111
+
112
+ `term` はガイド・画面・CLI での呼び方に合わせ、言い換えや過去の表記は `aliases` に置く。英語の見出しと `englishName` は小文字とし、大文字が定着した概念名(Kata)と固有名詞(SpecDojo)は例外とする。
113
+
114
+ - 良い例: `term: つけ`、`englishName: sale on credit`、`aliases: [ツケ, 掛け売り]`。
115
+ - 悪い例: 「つけ」を `term: 売掛債権取引`、英語名を `Sale On Credit` とする。
116
+
117
+ ### 6.5. 定義・注記・根拠の判断
118
+
119
+ `definition` は一文を基本とする。`notes` は定義を繰り返さない。設定・コマンドとの対応は理解に必要な範囲に絞り、独立した概念は分ける。
120
+
121
+ - 良い例: つけの注記は「店主が認めた常連客だけが利用する。」とし、残高・限度額は別の用語にする。
122
+ - 悪い例: 定義を「つけとはツケのこと。」で済ませる。
123
+ - schema の条件付き規則は用語間の関係で短く説明し、厳密な条件は `source` へ委ねる。
124
+ - 良い例: 「つけは常連客に認める後払いの販売で、つけ残高を管理する。」
125
+ - 悪い例: schema の `if` / `then` と必須キー一覧を注記へ写す。
126
+
127
+ ### 6.6. 分類・関連用語の判断
87
128
 
88
- - `tm-` の命名は「名詞」を基本とする(例: `tm-reorder-point`)。
89
- - 略語を使う場合は、業務用語集で一般的に通じるものに限定し、必要なら `definition` に補足する。
129
+ `category`・`relatedTerms` は同じ用語集の ID に限り、関連語は同じ文脈で理解すべきものに絞る。領域外の関係は `notes` または `source` に正本リンクと必要な用語 ID を示す。
90
130
 
91
- ### 6.2. 定義の書き方
131
+ - 良い例: 同じファイルの「販売」を分類に使い、別ファイルの「商品」は文書リンクで案内する。
132
+ - 悪い例: 未定義の分類名や別ファイルの ID を指定する、分類のためだけに共通用語を複製する。
133
+ - 参照検査が扱うのはファイル内の ID 重複と参照先の存在だけで、BDD・BR の参照は検査しない。業務の受入確認では用語集を横断して ID の一意性・翻訳以外の概念重複を照合し、参照元で意味と呼び方が一致すれば合格とする。
92
134
 
93
- - 用語の定義は「一文で意味が通り、境界が分かる」ように書く。
94
- - 単なる同義語の羅列にならないようにし、他と区別できる条件を明記する。
95
- - 未確定事項や仮置き情報は、共通ラベル(`_TODO_` / `_UNDECIDED_` / `_ASSUMPTION_`)で記述する。
135
+ ### 6.7. 改訂・廃止時の判断
96
136
 
97
- ### 6.3. 関連用語と分類の運用
137
+ ID・意味・採用状態の変更影響は、BDD・BR の用語参照、画面・CLI、実装、テスト・受入条件、表示ページで照合する。表示ページは YAML から `specdojo build --only yaml-pages` で再生成し、定義・分類・関連用語の一致を確認する。
98
138
 
99
- - `relatedTerms` および `category` は、**同じ用語集の中に存在する用語ID(`tm-...`)** を指定する。
100
- - 関連が強い(同じ業務文脈でセットで出る)ものを中心にし、増やしすぎない。
101
- - 用語の参照関係は `validate:schema` の一環として検証される。存在しない ID への参照や、用語 ID の重複がある場合は検証エラーとなる。
139
+ - 良い例: 意味が変わる語は新 ID とし、旧用語は `status: deprecated` と後継の注記を持ち、参照元を更新する。
140
+ - 悪い例: 旧 ID を別の意味に上書きする、参照元を確認せず削除する。
102
141
 
103
142
  ## 7. 禁止事項
104
143
 
105
- - 用語IDを未採番のままにすること、または重複させること。
106
- - 用語IDを意味の違う用語に使い回すこと。
107
- - `definition` を曖昧に書くこと(例: 「正しく処理される」「いい感じの在庫」など)。
108
- - 用語の説明に実装詳細(物理テーブル名、内部クラス名、SQL 等)を混ぜること。
109
- - 同じ概念を別名で重複登録し、`aliases` で統合しないこと。
110
- - 1 つのファイル内で言語を混在させること。
111
- - 章番号なし見出しを使用したり、章番号末尾の `.` を省略したりすること。
144
+ - 用語 ID の未採番・重複・意味の異なる語への再利用・確定後の改名。
145
+ - 意味を識別できない定義(「いい感じの在庫」など)。
146
+ - 別名を別概念として定義すること、翻訳以外で領域間に同じ概念を複製すること。
147
+ - 概念の説明を実装詳細・条件一覧で代用すること、編集手順・YAML 記法を `notes` に書くこと。
@@ -3,11 +3,11 @@ specdojo:
3
3
  id: specdojo:ifd-mermaid-rulebook
4
4
  type: rulebook
5
5
  deliverable_type: architecture
6
- status: draft
6
+ status: ready
7
7
  target_format: markdown
8
- recipe: undecided
8
+ recipe: specdojo:ifd-recipe
9
9
  sample: specdojo:ifd-sample
10
- template: undecided
10
+ template: specdojo:ifd-template
11
11
  based_on:
12
12
  - specdojo:rulebook-authoring-standard
13
13
  ---
@@ -16,283 +16,93 @@ specdojo:
16
16
 
17
17
  Infrastructure Flow Diagram (IFD) Documentation Rules using Mermaid
18
18
 
19
- 本ドキュメントは、アーキテクチャ検討・合意形成のために **インフラ構成図** を Mermaid の `flowchart` で記述するための標準ルールを定義します。
19
+ 実行環境・ネットワーク・信頼境界と主要な通信経路を合意するための規約を定める。
20
20
 
21
- IFD は、インフラの **論理的な境界(環境 / ネットワーク / ゾーン)** と、主要コンポーネント間の **通信の流れ** を示すことを目的とします。
21
+ ## 1. 全体方針
22
22
 
23
- 以下の内容は IFD の責務外とし、別ドキュメントで扱います。
23
+ - 上位の要素を実行場所へ対応付け、配置の事実・仮定・未決事項を区別する。
24
+ - 同じホスト上でも管理主体・到達範囲が異なる境界は区別する。
25
+ - 通信は障害の影響範囲と検証対象を識別できる粒度で示す。
26
+ - CIDR、IP、ポート、台数、版、認証値、FW・IAM 設定、コマンド構文は載せず、技術構成・連携・運用の正本へ委ねる。
27
+ - 共通の運用: 役割の割り当ては適用先のメンバー定義に、`status` の昇格と承認、改訂と廃止、未決事項の引き継ぎは [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従う。文書の整形・lint はリポジトリの検証で扱い、成果物の検証観点に含めない。
24
28
 
25
- - 物理構成(CIDR、IP、ポート、AZ)
26
- - スケーリング、冗長化、台数
27
- - セキュリティ設定(FW / SG / IAM)
28
- - 技術選定・製品名の詳細
29
+ ## 2. 位置づけと用語定義
29
30
 
30
- ## 1. 設計思想(最重要)
31
+ | 用語 | 本書での意味 |
32
+ | ---------------- | ------------------------------------------------------------------ |
33
+ | ネットワーク境界 | 到達経路・接続条件が変わる区切り。物理構成と一致するとは限らない |
34
+ | 論理ゾーン | 管理主体、公開範囲、情報の持ち出し条件を検討する区切り |
35
+ | 上位構成図 | 責務を定義する入力。論理的なコンテナと実行用コンテナを同一視しない |
31
36
 
32
- - Mermaid は図ではなく **「構造化テキスト」** として扱う。
33
- - 生成 AI は特に以下を **意味として解釈** する:
34
- - **ノード名**(役割)
35
- - **境界(subgraph)**(実行環境 / ネットワーク / ゾーン)
36
- - **矢印の方向**(入口 → 処理 → 永続化)
37
- - 見栄えは **配置・命名・色の一貫性** によって担保する。
37
+ ## 3. ファイル命名・ID規則
38
38
 
39
- 指針:**「装飾より構造」**
39
+ - ファイル名は `ifd-<target>.md` とし、`id` は stem と対応させる。共通規則は [[specdojo:docs-structure-guide|ドキュメント構造ガイド]] を正とする。
40
+ - Mermaid のノード ID と表示名を分離し、改訂時も同じ要素・経路の ID を維持する。
40
41
 
41
- ## 2. 図タイプ・方向の固定(必須)
42
+ ## 4. 推奨 Frontmatter 項目
42
43
 
43
- IFD は以下の形式に固定します。
44
+ 共通の値・構文は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] を正とする。
44
45
 
45
- ````markdown
46
- ```mermaid
47
- flowchart LR
48
- ```
49
- ````
46
+ | 項目 | 扱い | IFD での用途 |
47
+ | ------------------------ | -------- | ---------------------------------------------------- |
48
+ | `rulebook` | 必須 | `specdojo:ifd-mermaid-rulebook` を指定する |
49
+ | `based_on` | 条件付き | 直接の根拠となる上位構成図。単なる参考文書は含めない |
50
+ | `part_of` / `supersedes` | 条件付き | 所属・置き換え関係がある場合に記載する |
50
51
 
51
- ### 2.1. 理由
52
+ ## 5. 本文要件
52
53
 
53
- - `flowchart LR` に固定することで **通信方向 = 左 → 右** が一貫し、生成AIが推論しやすくなる。
54
+ 骨組みは template を正本とし、以下は内容の成立条件である。
54
55
 
55
- ### 2.2. 禁止
56
+ | 内容 | 必須性 | 判定条件 |
57
+ | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------ |
58
+ | 概要 | 必須 | 対象環境、図で判断すること、上位入力、対象外を識別できる |
59
+ | インフラ構成図 | 必須 | 実行場所、必要な境界、主要経路を Mermaid で示し、凡例で向き・線種・省略を説明する |
60
+ | 配置と境界の定義 | 必須 | 要素に管理主体・保持情報・到達条件を対応付け、上位要素の配置か対象外かを示す。代替配置は適用条件を示す |
61
+ | 通信経路と情報の境界 | 必須 | 図と本文の経路 ID・起点・終点が対応し、目的、情報の要点、利用条件、詳細の正本を追える |
62
+ | 技術前提・制約と検証観点 | 必須 | 隔離・認証・公開の前提と、境界別の障害影響・観測対象を示す |
63
+ | メモ / 将来課題 | 条件付き | 仮定・未決事項がある場合、論点と影響(当面の扱い)を残す |
56
64
 
57
- - `TB` / `RL` / `BT`
58
- - 図中での方向混在
65
+ ### 5.1. Mermaid の表現規約
59
66
 
60
- ## 3. 境界(subgraph)ルール(最大3階層)
67
+ - `flowchart LR` を使う。矢印は主たる起点から終点へ向け、応答は同じ線に含める。独立した逆方向の起動だけを別線にする。
68
+ - `subgraph` は最大 3 階層とし、必要な境界だけを描いて各枠が何の区切りか明記する。
69
+ - 表示名は役割を主語とし、製品名は「推論サービス(製品名)」のように補記する。
70
+ - 処理は矩形、DB は円筒、ファイル保管は角丸を基本とし、形状・色・絵文字だけに意味を持たせない。
71
+ - 経路ラベルに ID と通信目的を付け、プロトコル名だけにしない。線種を分ける場合は凡例で定義する。
72
+ - 中継を省略して一本で描く場合は、図の近傍で中継と到達条件を説明し、直接接続と誤読させない。
73
+ - 色は `classDef` で役割の分類を統一する。交差が判断を妨げる場合は範囲を分割し、共有要素と経路 ID を対応付ける。
74
+ - 図の確認: 「インフラ構成図」章の全 Mermaid ブロックの構文を `npm run lint:mermaid` で確かめ、描画プレビューで表示名・経路ラベル・枠名が読めること、枠の包含が「配置と境界の定義」と一致することを確かめる。
61
75
 
62
- 境界は **最大3階層** までとし、意味を固定します。
76
+ ## 6. 記述ガイド
63
77
 
64
- | レベル | 意味 | 例 |
65
- | ------ | ------------ | ----------------------- |
66
- | Lv1 | 実行環境 | Cloud / On-Prem / SaaS |
67
- | Lv2 | ネットワーク | VPC / Project / Segment |
68
- | Lv3 | 論理ゾーン | Public / Private |
78
+ ### 6.1. 概要
69
79
 
70
- ### 3.1. 例
80
+ 対象環境と判断範囲を先に選ぶ。良い例は「店舗端末から共有サービスまでの到達範囲を示し、通信不能時の切り分けに使う」。悪い例は「システム全体を説明する」。
71
81
 
72
- ```mermaid
73
- flowchart LR
74
- subgraph Cloud["Cloud Environment"]
75
- subgraph VPC["VPC"]
76
- subgraph Public["Public Zone"]
77
- end
78
- subgraph Private["Private Zone"]
79
- end
80
- end
81
- end
82
- ```
82
+ ### 6.2. インフラ構成図
83
83
 
84
- ### 3.2. 禁止
84
+ 枠を越えるごとに実行場所・接続条件・管理主体のどれが変わるかで描き分ける。良い例は「店舗端末と外部保管サービスを別枠にし、送信する記録をラベルにする」。悪い例は「同じ製品なので外部サービスも端末の枠に入れる」。
85
85
 
86
- - Lv4 以上の subgraph
87
- - Subnet CIDR、AZ 名、IP、ポート番号などの物理情報
88
- - 業務概念(例:Order Management)を境界名に使うこと
86
+ ### 6.3. 配置と境界の定義
89
87
 
90
- ## 4. ノード命名規約(最重要)
88
+ 図にない管理責務・保持情報を補う。推奨列は「図中の環境・要素、上位要素、管理主体、情報・到達条件」。良い例は「作業記録は端末側、外部には送信対象だけを渡す案」。悪い例は「Private 枠なので安全」。
91
89
 
92
- ### 4.1. 表示名は「役割名」で統一する
90
+ 代替配置が選択肢なら、置き換え後の保持範囲・到達性を確認対象にする。良い例は「ホストで同じ役割を実行し、書込範囲を再確認する」。悪い例は「両環境に同名の処理を置き、稼働条件を示さない」。
93
91
 
94
- - 表示名は **役割(Role)** を表す
95
- - 製品名 / サービス名 / 略語は使用しない
96
- - 英語・単数形を基本とする
92
+ ### 6.4. 通信経路と情報の境界
97
93
 
98
- #### 4.1.1. OK
94
+ 条件付きの外部依存を常時必須の経路と混ぜない。推奨列は「経路 ID、起点 → 終点、目的・情報、利用条件・詳細の委譲先」。良い例は「共有時だけ控えを外部へ送り、接続・認証の契約は連携仕様で定める」。悪い例は「全データを同期する」。
99
95
 
100
- - `Load Balancer`
101
- - `Web App`
102
- - `API Server`
103
- - `Relational Database`
104
- - `Object Storage`
105
- - `Cache`
106
- - `Message Queue`
96
+ ### 6.5. 技術前提・制約と検証観点
107
97
 
108
- #### 4.1.2. NG
98
+ 境界が成立する条件と、崩れたときに観測するものを結ぶ。良い例は「別ホストへの到達不能、応答欠落、保存失敗を分けて観測する」。悪い例は「トンネルがつながるので作業も成功する」。検証設計への入力と実施済みの証跡を区別し、閾値や復旧コマンドを再定義しない。
109
99
 
110
- - `ALB`
111
- - `EC2`
112
- - `Cloud Run`
113
- - `RDS`
114
- - `Redis` / `Kafka`(※技術選定は別ドキュメント)
100
+ ### 6.6. メモ / 将来課題
115
101
 
116
- ### 4.2. 絵文字アイコン(任意)
102
+ 不明点が配置・境界・経路のどこに効くかで影響を具体化する。良い例は「公開先が未決のため公開経路は仮定とし、決まったら枠と経路を直す」。悪い例は「後で検討する」。
117
103
 
118
- 絵文字は **人間の視認性向上** には有効ですが、表示差や幅崩れが起きる環境もあるため、次のルールで運用します。
104
+ ## 7. 禁止事項
119
105
 
120
- - 絵文字は **任意**(なくても成立する)
121
- - 絵文字は **表示名(Label)のみに付ける**(IDには付けない)
122
- - **1ノード1個まで**、表示名の **先頭に付ける**
123
- - 絵文字だけに頼らず、必ず役割名テキストも併記する
124
-
125
- OK:
126
-
127
- ```mermaid
128
- flowchart LR
129
- lb["🧭 Load Balancer"]
130
- db[("🗄️ Relational Database")]
131
- cache{{"⚡ Cache"}}
132
- ```
133
-
134
- NG:
135
-
136
- ```text
137
- flowchart LR
138
- 🧭lb["Load Balancer"]
139
- ```
140
-
141
- ## 5. ノードIDと表示名を分離する(必須)
142
-
143
- Mermaid のノードは **ID(参照用)と表示名(意味)を分離** します。
144
-
145
- ```mermaid
146
- flowchart LR
147
- lb["🧭 Load Balancer"]
148
- web["🖥️ Web App"]
149
- api["⚙️ API Server"]
150
- db[("🗄️ Relational Database")]
151
- ```
152
-
153
- ### 5.1. 狙い
154
-
155
- - ノード参照が安定する
156
- - 生成AIがノード同士の関係を誤解しにくくなる
157
-
158
- ## 6. 記法(形=意味を固定)
159
-
160
- ノード形状を **意味として固定** します(役割名だけでなく形でも読み取れるようにする)。
161
-
162
- | 種類 | 意味(役割) | 記法 | 表示名の例 |
163
- | -------------- | ----------------------------- | ---------------- | ------------------------ |
164
- | 🗄️ Database | 永続DB | `db[("...")]` | `🗄️ Relational Database` |
165
- | 🪣 Storage | オブジェクト/ファイル保管 | `storage("...")` | `🪣 Object Storage` |
166
- | 📨 Queue/Topic | 非同期連携(キュー/トピック) | `queue[["..."]]` | `📨 Message Queue` |
167
- | ⚡ Cache | 参照高速化(任意) | `cache{{"..."}}` | `⚡ Cache` |
168
-
169
- ### 6.1. 例
170
-
171
- ```mermaid
172
- flowchart LR
173
- db[("🗄️ Relational Database")]
174
- storage("🪣 Object Storage")
175
- queue[["📨 Message Queue"]]
176
- cache{{"⚡ Cache"}}
177
- ```
178
-
179
- 補足:
180
-
181
- - Cache と Storage を分けるかは、図で合意したい論点(境界/経路/責務)がある場合のみ分ければ十分です。
182
- - Cache を描かない場合も、このルールに反しません。
183
-
184
- ## 7. 通信矢印のルール(意味重視)
185
-
186
- ### 7.1. 原則は片方向
187
-
188
- ```mermaid
189
- flowchart LR
190
- A --> B
191
- ```
192
-
193
- ### 7.2. 双方向通信
194
-
195
- ```mermaid
196
- flowchart LR
197
- A --> B
198
- B --> A
199
- ```
200
-
201
- ### 7.3. 矢印ラベルのルール
202
-
203
- - ラベルは **通信の意味** を表す場合のみ使用する
204
- - プロトコル名・ポート番号は記載しない
205
-
206
- #### 7.3.1. OK
207
-
208
- ```mermaid
209
- flowchart LR
210
- api -->|Authenticate| auth
211
- ```
212
-
213
- #### 7.3.2. NG
214
-
215
- ```mermaid
216
- flowchart LR
217
- api -->|HTTPS 443| db
218
- ```
219
-
220
- ## 8. 見栄えを整える最小限スタイル(任意)
221
-
222
- ### 8.1. 原則
223
-
224
- - 色は **境界単位** または **役割の大分類** で付ける
225
- - ノード単位でバラバラな色付けはしない
226
- - `classDef` のみ使用可、`style` は原則使用しない
227
-
228
- ### 8.2. 例
229
-
230
- ```mermaid
231
- flowchart LR
232
- lb["🧭 Load Balancer"]
233
- web["🖥️ Web App"]
234
- api["⚙️ API Server"]
235
- cache{{"⚡ Cache"}}
236
- db[("🗄️ Relational Database")]
237
- storage("🪣 Object Storage")
238
-
239
- classDef boundary fill:#f5f7fa,stroke:#999,color:#000
240
- classDef compute fill:#e3f2fd,stroke:#1e88e5,color:#000
241
- classDef data fill:#e8f5e9,stroke:#43a047,color:#000
242
-
243
- class lb,web,api compute
244
- class cache,db,storage data
245
- ```
246
-
247
- ## 9. 完成例(推奨テンプレート)
248
-
249
- ```mermaid
250
- flowchart LR
251
- classDef boundary fill:#f5f7fa,stroke:#999,color:#000
252
- classDef compute fill:#e3f2fd,stroke:#1e88e5,color:#000
253
- classDef data fill:#e8f5e9,stroke:#43a047,color:#000
254
-
255
- user["👤 User"] --> internet["🌐 Internet"]
256
-
257
- subgraph Cloud["☁️ Cloud Environment"]
258
- subgraph VPC["🛡️ VPC"]
259
- subgraph Public["🌍 Public Zone"]
260
- lb["🧭 Load Balancer"]
261
- end
262
-
263
- subgraph Private["🔒 Private Zone"]
264
- web["🖥️ Web App"]
265
- api["⚙️ API Server"]
266
- cache{{"⚡ Cache"}}
267
- db[("🗄️ Relational Database")]
268
- storage("🪣 Object Storage")
269
- end
270
- end
271
- end
272
-
273
- internet --> lb
274
- lb --> web
275
- web --> api
276
- api --> cache
277
- api --> db
278
- api --> storage
279
-
280
- class user,internet boundary
281
- class lb,web,api compute
282
- class cache,db,storage data
283
- ```
284
-
285
- ### 9.1. この図で合意できること
286
-
287
- - ネットワーク境界(Public / Private)
288
- - 主要コンポーネントの役割分担
289
- - 主要な通信フロー
290
- - 永続化先の種別(🗄️/🪣)と非同期の有無(📨)
291
-
292
- ## 10. 禁止事項
293
-
294
- - 物理構成の詳細(CIDR、IP、ポート、AZ、台数、Auto Scaling 等)
295
- - 技術選定の詳細(特定クラウドサービス名、製品名)
296
- - 意味のないラベル(HTTPS / TCP / 443 等)
297
- - 方向の混在
298
- - 矢印の過剰な交差(読みづらくなった場合は境界整理または図を分割する)
106
+ - 上位図の責務を変更したり、業務判断・公開可否・製品採択を根拠なく確定したりしない。
107
+ - 論理ゾーンやトンネルの存在だけから、隔離・認証・情報非保持を保証しない。
108
+ - 詳細設定・schema・リファレンスの値、構文、構造を複製しない。秘密値や個人固有の接続先を載せない。
@@ -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から参照する運用を推奨します。