specdojo 0.7.0 → 0.8.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 (337) hide show
  1. package/.github/agents/specdojo-orchestrator.md +3 -2
  2. package/CHANGELOG.md +153 -0
  3. package/dist/catalog/build.js +24 -1
  4. package/dist/catalog/plan.js +1 -1
  5. package/dist/catalog/scaffold.js +4 -1
  6. package/dist/commands/init.js +5 -1
  7. package/dist/commands/night-orchestrator.js +6 -4
  8. package/dist/dashboard/dashboard-timeline.js +18 -16
  9. package/dist/dashboard/dashboard.js +612 -259
  10. package/dist/dashboard/epic-plan.js +81 -0
  11. package/dist/dashboard/exec-records.js +16 -20
  12. package/dist/dashboard/routines.js +8 -6
  13. package/dist/dashboard/timeline-build.js +5 -9
  14. package/dist/dashboard/timeline.js +9 -4
  15. package/dist/devcontainer/scaffold.js +18 -0
  16. package/dist/docs/frontmatter-namespace.js +1 -48
  17. package/dist/docs/yaml-pages.js +125 -3
  18. package/dist/exec/agent-config.js +22 -0
  19. package/dist/exec/agent-plan.js +3 -2
  20. package/dist/exec/commands.js +69 -21
  21. package/dist/exec/commit-hook-skips.js +78 -0
  22. package/dist/exec/core.js +19 -7
  23. package/dist/exec/events.js +159 -8
  24. package/dist/exec/evidence.js +64 -16
  25. package/dist/exec/handoff.js +9 -13
  26. package/dist/exec/limit.js +1 -1
  27. package/dist/exec/mechanical-result.js +45 -0
  28. package/dist/exec/migrate-records.js +249 -0
  29. package/dist/exec/parent-validation.js +153 -12
  30. package/dist/exec/pipeline-state.js +27 -5
  31. package/dist/exec/plans-condense-findings.js +89 -0
  32. package/dist/exec/plans-core.js +24 -17
  33. package/dist/exec/plans-generation.js +48 -25
  34. package/dist/exec/plans-grade-findings.js +8 -3
  35. package/dist/exec/plans-kata-findings.js +61 -0
  36. package/dist/exec/plans-planning.js +3 -3
  37. package/dist/exec/plans-storage.js +12 -24
  38. package/dist/exec/register-resume.js +55 -56
  39. package/dist/exec/register.js +26 -22
  40. package/dist/exec/repo-integration-sync.js +8 -4
  41. package/dist/exec/repo-integration.js +21 -1
  42. package/dist/exec/reporter.js +121 -23
  43. package/dist/exec/results.js +85 -24
  44. package/dist/exec/review-completion.js +47 -0
  45. package/dist/exec/review-kata.js +109 -0
  46. package/dist/exec/run/agent-pipeline.js +75 -6
  47. package/dist/exec/run/agent.js +20 -7
  48. package/dist/exec/run/in-place.js +69 -32
  49. package/dist/exec/run/job.js +81 -24
  50. package/dist/exec/run/lifecycle-commands.js +188 -36
  51. package/dist/exec/run/mode-shared.js +11 -3
  52. package/dist/exec/run/register-command.js +6 -10
  53. package/dist/exec/run/register-core.js +20 -13
  54. package/dist/exec/run/register-mode.js +12 -12
  55. package/dist/exec/run/register-post-review.js +21 -9
  56. package/dist/exec/run/register-resume.js +28 -18
  57. package/dist/exec/run/register-state.js +10 -7
  58. package/dist/exec/run/register-worktree.js +60 -30
  59. package/dist/exec/run/schedule-mode.js +4 -4
  60. package/dist/exec/run/schedule-prepare.js +201 -59
  61. package/dist/exec/run/schedule-task.js +129 -25
  62. package/dist/exec/run/shared.js +4 -3
  63. package/dist/exec/run/trailing-records.js +35 -0
  64. package/dist/exec/run-records.js +2 -0
  65. package/dist/exec/strategy.js +1 -0
  66. package/dist/exec/trailing-records.js +242 -0
  67. package/dist/exec/trial-commands.js +3 -2
  68. package/dist/exec/validate-records-commit.js +110 -0
  69. package/dist/exec/validate-records.js +148 -0
  70. package/dist/exec/worktree-command.js +29 -16
  71. package/dist/exec/worktree-ops-commit.js +119 -48
  72. package/dist/exec/worktree-ops-lifecycle.js +77 -48
  73. package/dist/exec/worktree-ops-merge.js +13 -2
  74. package/dist/exec/worktree-ops.js +2 -2
  75. package/dist/exec/worktree.js +19 -2
  76. package/dist/grade/apply.js +32 -6
  77. package/dist/grade/command-inspect.js +2 -2
  78. package/dist/grade/command-run.js +2 -0
  79. package/dist/grade/command-shared.js +1 -1
  80. package/dist/grade/core.js +18 -5
  81. package/dist/grade/markdown.js +3 -3
  82. package/dist/grade/pipeline-state.js +15 -11
  83. package/dist/grade/plan.js +37 -17
  84. package/dist/grade/result.js +3 -3
  85. package/dist/grade/run.js +23 -3
  86. package/dist/grade/target-discovery.js +17 -4
  87. package/dist/grade/targets.js +12 -11
  88. package/dist/job/job.js +31 -17
  89. package/dist/job/noop.js +104 -0
  90. package/dist/register/core.js +2 -0
  91. package/dist/register/create-commands.js +28 -3
  92. package/dist/register/deliverable-target.js +9 -1
  93. package/dist/register/epic.js +104 -26
  94. package/dist/register/event-merge.js +3 -0
  95. package/dist/register/events.js +4 -0
  96. package/dist/register/external-project.js +3 -0
  97. package/dist/register/item.js +6 -0
  98. package/dist/register/maintenance-commands.js +4 -1
  99. package/dist/register/planning.js +7 -14
  100. package/dist/register/register.js +43 -9
  101. package/dist/register/track-domains.js +34 -0
  102. package/dist/register/track-plan.js +78 -0
  103. package/dist/register/transition-commands.js +8 -0
  104. package/dist/register/work-table.js +64 -0
  105. package/dist/review/grade.js +35 -13
  106. package/dist/routine/definition.js +4 -3
  107. package/dist/routine/failure.js +30 -0
  108. package/dist/routine/routine.js +56 -32
  109. package/dist/routine/storage.js +33 -0
  110. package/dist/schedule/schedule.js +1 -0
  111. package/dist/schedule/strategy-generate-document.js +26 -14
  112. package/dist/schedule/strategy-generate-scope.js +17 -45
  113. package/dist/schedule/strategy-generate.js +33 -3
  114. package/dist/schedule/strategy-profiles.js +86 -12
  115. package/dist/shared/agent-types.js +2 -0
  116. package/dist/shared/condense-records.js +25 -0
  117. package/dist/shared/deprecation.js +8 -0
  118. package/dist/shared/document-metadata.js +20 -0
  119. package/dist/shared/finding-cause.js +20 -0
  120. package/dist/shared/frontmatter-namespace.js +48 -0
  121. package/dist/shared/git.js +142 -15
  122. package/dist/shared/grade-result.js +17 -1
  123. package/dist/shared/local-state.js +20 -0
  124. package/dist/shared/markdownlint-config.js +8 -3
  125. package/dist/shared/plan-conventions.js +129 -0
  126. package/dist/shared/plan-templates.js +57 -41
  127. package/dist/shared/run-records.js +224 -0
  128. package/dist/shared/specdojo-config.js +39 -21
  129. package/dist/shared/text.js +65 -5
  130. package/dist/shared/timeline-index.js +2 -0
  131. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +9 -2
  132. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +4 -74
  133. package/docs/ja/specdojo/exec-templates/xep-condense-template.md +50 -0
  134. package/docs/ja/specdojo/exec-templates/xep-draft-template.md +17 -5
  135. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +16 -3
  136. package/docs/ja/specdojo/exec-templates/xep-recipe-guided-template.md +15 -5
  137. package/docs/ja/specdojo/exec-templates/xep-recipe-maintenance-template.md +6 -0
  138. package/docs/ja/specdojo/exec-templates/xep-register-template.md +1 -1
  139. package/docs/ja/specdojo/exec-templates/xep-rulebook-maintenance-template.md +6 -0
  140. package/docs/ja/specdojo/exec-templates/xep-sample-maintenance-template.md +6 -0
  141. package/docs/ja/specdojo/exec-templates/xep-template-maintenance-template.md +6 -0
  142. package/docs/ja/specdojo/exec-templates/xer-condense-template.md +25 -0
  143. package/docs/ja/specdojo/exec-templates/xp-common-conventions-template.md +50 -0
  144. package/docs/ja/specdojo/exec-templates/xrp-common-conventions-template.md +30 -0
  145. package/docs/ja/specdojo/guides/branch-workflow-guide.md +1 -1
  146. package/docs/ja/specdojo/guides/docs-editing-guide.md +12 -0
  147. package/docs/ja/specdojo/guides/docs-structure-guide.md +48 -15
  148. package/docs/ja/specdojo/guides/exec-config-guide.md +47 -16
  149. package/docs/ja/specdojo/guides/exec-operation-guide.md +53 -17
  150. package/docs/ja/specdojo/guides/exec-worktree-guide.md +20 -11
  151. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +92 -55
  152. package/docs/ja/specdojo/guides/project-move-guide.md +381 -0
  153. package/docs/ja/specdojo/guides/quick-start-guide.md +70 -14
  154. package/docs/ja/specdojo/guides/register-operation-guide.md +25 -5
  155. package/docs/ja/specdojo/guides/remote-host-development-guide.md +2 -0
  156. package/docs/ja/specdojo/guides/review-guide.md +22 -19
  157. package/docs/ja/specdojo/guides/routine-operation-guide.md +14 -8
  158. package/docs/ja/specdojo/guides/ryu-guide.md +23 -13
  159. package/docs/ja/specdojo/guides/schedule-design-guide.md +7 -4
  160. package/docs/ja/specdojo/guides/schedule-operation-guide.md +27 -3
  161. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +5 -4
  162. package/docs/ja/specdojo/guides/timeline-design-guide.md +27 -144
  163. package/docs/ja/specdojo/guides/use-case-guide.md +92 -155
  164. package/docs/ja/specdojo/recipes/bac-recipe.md +94 -0
  165. package/docs/ja/specdojo/recipes/bes-recipe.md +105 -0
  166. package/docs/ja/specdojo/recipes/br-recipe.md +84 -0
  167. package/docs/ja/specdojo/recipes/cdfd-uc-recipe.md +36 -24
  168. package/docs/ja/specdojo/recipes/cnd-recipe.md +125 -0
  169. package/docs/ja/specdojo/recipes/cpd-recipe.md +126 -0
  170. package/docs/ja/specdojo/recipes/cxd-recipe.md +145 -0
  171. package/docs/ja/specdojo/recipes/ifd-recipe.md +134 -0
  172. package/docs/ja/specdojo/recipes/ifx-cmd-recipe.md +135 -86
  173. package/docs/ja/specdojo/recipes/ifx-index-recipe.md +130 -0
  174. package/docs/ja/specdojo/recipes/pm-organization-recipe.md +29 -26
  175. package/docs/ja/specdojo/recipes/pm-plan-recipe.md +35 -26
  176. package/docs/ja/specdojo/recipes/pm-quality-management-plan-recipe.md +38 -28
  177. package/docs/ja/specdojo/recipes/pm-raci-recipe.md +39 -31
  178. package/docs/ja/specdojo/recipes/pm-roles-recipe.md +26 -28
  179. package/docs/ja/specdojo/recipes/prj-assumptions-constraints-dependencies-recipe.md +10 -8
  180. package/docs/ja/specdojo/recipes/prj-comparison-of-alternatives-recipe.md +18 -17
  181. package/docs/ja/specdojo/recipes/stsd-recipe.md +100 -62
  182. package/docs/ja/specdojo/recipes/sysd-critical-flows-recipe.md +106 -0
  183. package/docs/ja/specdojo/recipes/sysd-cross-cutting-policy-recipe.md +137 -0
  184. package/docs/ja/specdojo/recipes/sysd-index-recipe.md +122 -0
  185. package/docs/ja/specdojo/references/command-reference.md +79 -64
  186. package/docs/ja/specdojo/references/deliverables-reference.md +9 -4
  187. package/docs/ja/specdojo/references/directory-layout-reference.md +3 -2
  188. package/docs/ja/specdojo/references/specdojo-config-reference.md +17 -16
  189. package/docs/ja/specdojo/rulebooks/bac-rulebook.md +72 -290
  190. package/docs/ja/specdojo/rulebooks/bdd-rulebook.md +212 -79
  191. package/docs/ja/specdojo/rulebooks/bds-rulebook.md +138 -154
  192. package/docs/ja/specdojo/rulebooks/bes-index-rulebook.md +147 -59
  193. package/docs/ja/specdojo/rulebooks/bes-rulebook.md +100 -96
  194. package/docs/ja/specdojo/rulebooks/br-rulebook.md +88 -108
  195. package/docs/ja/specdojo/rulebooks/ccd-mermaid-rulebook.md +126 -211
  196. package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +56 -35
  197. package/docs/ja/specdojo/rulebooks/cdsd-rulebook.md +102 -68
  198. package/docs/ja/specdojo/rulebooks/cdt-rulebook.md +152 -0
  199. package/docs/ja/specdojo/rulebooks/cld-rulebook.md +9 -184
  200. package/docs/ja/specdojo/rulebooks/clis-rulebook.md +187 -0
  201. package/docs/ja/specdojo/rulebooks/cnd-rulebook.md +93 -247
  202. package/docs/ja/specdojo/rulebooks/cpd-rulebook.md +104 -241
  203. package/docs/ja/specdojo/rulebooks/cxd-rulebook.md +124 -257
  204. package/docs/ja/specdojo/rulebooks/dct-index-rulebook.md +87 -98
  205. package/docs/ja/specdojo/rulebooks/dct-rulebook.md +9 -7
  206. package/docs/ja/specdojo/rulebooks/dec-rulebook.md +2 -1
  207. package/docs/ja/specdojo/rulebooks/dss-rulebook.md +193 -0
  208. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +100 -54
  209. package/docs/ja/specdojo/rulebooks/ifd-mermaid-rulebook.md +69 -252
  210. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +91 -76
  211. package/docs/ja/specdojo/rulebooks/ifx-file-rulebook.md +252 -226
  212. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +118 -40
  213. package/docs/ja/specdojo/rulebooks/imp-business-rulebook.md +11 -11
  214. package/docs/ja/specdojo/rulebooks/imp-data-rulebook.md +9 -9
  215. package/docs/ja/specdojo/rulebooks/imp-interface-rulebook.md +4 -4
  216. package/docs/ja/specdojo/rulebooks/imp-operations-rulebook.md +11 -11
  217. package/docs/ja/specdojo/rulebooks/imp-test-rulebook.md +11 -11
  218. package/docs/ja/specdojo/rulebooks/mm-rulebook.md +4 -3
  219. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +34 -29
  220. package/docs/ja/specdojo/rulebooks/pm-change-request-log-rulebook.md +8 -8
  221. package/docs/ja/specdojo/rulebooks/pm-issue-log-rulebook.md +2 -2
  222. package/docs/ja/specdojo/rulebooks/pm-organization-rulebook.md +50 -56
  223. package/docs/ja/specdojo/rulebooks/pm-plan-rulebook.md +46 -55
  224. package/docs/ja/specdojo/rulebooks/pm-quality-management-plan-rulebook.md +57 -54
  225. package/docs/ja/specdojo/rulebooks/pm-raci-rulebook.md +50 -65
  226. package/docs/ja/specdojo/rulebooks/pm-risk-register-rulebook.md +2 -2
  227. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +70 -97
  228. package/docs/ja/specdojo/rulebooks/pr-rulebook.md +2 -1
  229. package/docs/ja/specdojo/rulebooks/prj-assumptions-constraints-dependencies-rulebook.md +47 -56
  230. package/docs/ja/specdojo/rulebooks/prj-comparison-of-alternatives-rulebook.md +61 -135
  231. package/docs/ja/specdojo/rulebooks/sf-index-rulebook.md +116 -32
  232. package/docs/ja/specdojo/rulebooks/sf-rulebook.md +118 -61
  233. package/docs/ja/specdojo/rulebooks/sld-rulebook.md +152 -57
  234. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +51 -39
  235. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +101 -46
  236. package/docs/ja/specdojo/rulebooks/sysd-critical-flows-rulebook.md +72 -329
  237. package/docs/ja/specdojo/rulebooks/sysd-cross-cutting-policy-rulebook.md +74 -263
  238. package/docs/ja/specdojo/rulebooks/sysd-index-rulebook.md +78 -195
  239. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +4 -9
  240. package/docs/ja/specdojo/rulebooks/trc-requirements-to-specs-rulebook.md +3 -4
  241. package/docs/ja/specdojo/rulebooks/trc-requirements-to-tests-rulebook.md +3 -3
  242. package/docs/ja/specdojo/rulebooks/uis-rulebook.md +140 -143
  243. package/docs/ja/specdojo/samples/bac-sample.md +106 -21
  244. package/docs/ja/specdojo/samples/bdd-sample.yaml +143 -35
  245. package/docs/ja/specdojo/samples/bds-sample.md +100 -21
  246. package/docs/ja/specdojo/samples/bes-index-sample.md +59 -20
  247. package/docs/ja/specdojo/samples/bes-sample.md +80 -21
  248. package/docs/ja/specdojo/samples/br-sample.md +68 -14
  249. package/docs/ja/specdojo/samples/ccd-sample.md +81 -19
  250. package/docs/ja/specdojo/samples/cdfd-sample.md +172 -99
  251. package/docs/ja/specdojo/samples/cdfd-uc-sample.md +9 -7
  252. package/docs/ja/specdojo/samples/cdsd-sample.md +89 -20
  253. package/docs/ja/specdojo/samples/cdt-sample.md +116 -0
  254. package/docs/ja/specdojo/samples/cld-sample.md +3 -30
  255. package/docs/ja/specdojo/samples/clis-sample.md +132 -0
  256. package/docs/ja/specdojo/samples/cnd-sample.md +127 -21
  257. package/docs/ja/specdojo/samples/cpd-sample.md +136 -22
  258. package/docs/ja/specdojo/samples/cxd-sample.md +108 -22
  259. package/docs/ja/specdojo/samples/dct-index-sample.yaml +63 -17
  260. package/docs/ja/specdojo/samples/dss-sample.md +175 -0
  261. package/docs/ja/specdojo/samples/gl-sample.yaml +50 -14
  262. package/docs/ja/specdojo/samples/ifd-sample.md +105 -21
  263. package/docs/ja/specdojo/samples/ifx-cmd-sample.yaml +91 -60
  264. package/docs/ja/specdojo/samples/ifx-file-sample.md +462 -21
  265. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +87 -19
  266. package/docs/ja/specdojo/samples/pm-members-sample.yaml +37 -13
  267. package/docs/ja/specdojo/samples/pm-organization-sample.md +52 -20
  268. package/docs/ja/specdojo/samples/pm-plan-sample.md +84 -26
  269. package/docs/ja/specdojo/samples/pm-quality-management-plan-sample.md +55 -22
  270. package/docs/ja/specdojo/samples/pm-raci-sample.md +69 -28
  271. package/docs/ja/specdojo/samples/pm-roles-sample.yaml +13 -12
  272. package/docs/ja/specdojo/samples/prj-assumptions-constraints-dependencies-sample.md +50 -26
  273. package/docs/ja/specdojo/samples/prj-comparison-of-alternatives-sample.md +89 -62
  274. package/docs/ja/specdojo/samples/sf-index-sample.md +89 -20
  275. package/docs/ja/specdojo/samples/sf-sample.md +121 -21
  276. package/docs/ja/specdojo/samples/sld-sample.md +107 -21
  277. package/docs/ja/specdojo/samples/stsd-sample.md +54 -26
  278. package/docs/ja/specdojo/samples/sysd-critical-flows-sample.md +166 -21
  279. package/docs/ja/specdojo/samples/sysd-cross-cutting-policy-sample.md +178 -21
  280. package/docs/ja/specdojo/samples/sysd-index-sample.md +82 -21
  281. package/docs/ja/specdojo/samples/tml-sample.yaml +4 -1
  282. package/docs/ja/specdojo/samples/uis-sample.md +164 -20
  283. package/docs/ja/specdojo/standards/document-metadata-standard.md +33 -4
  284. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +3 -1
  285. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +1 -0
  286. package/docs/ja/specdojo/templates/bac-template.md +76 -0
  287. package/docs/ja/specdojo/templates/bes-template.md +56 -0
  288. package/docs/ja/specdojo/templates/br-template.md +64 -0
  289. package/docs/ja/specdojo/templates/cdfd-template.md +81 -54
  290. package/docs/ja/specdojo/templates/cdfd-uc-template.md +9 -5
  291. package/docs/ja/specdojo/templates/cnd-template.md +137 -0
  292. package/docs/ja/specdojo/templates/cpd-template.md +129 -0
  293. package/docs/ja/specdojo/templates/cxd-template.md +105 -0
  294. package/docs/ja/specdojo/templates/dct-data-model-cdt-template.yaml +40 -0
  295. package/docs/ja/specdojo/templates/dct-data-model-cld-template.yaml +7 -14
  296. package/docs/ja/specdojo/templates/dct-index-template.md +9 -20
  297. package/docs/ja/specdojo/templates/dct-project-management-template.yaml +5 -1
  298. package/docs/ja/specdojo/templates/ifd-template.md +86 -0
  299. package/docs/ja/specdojo/templates/ifx-cmd-template.yaml +44 -28
  300. package/docs/ja/specdojo/templates/ifx-index-template.yaml +40 -0
  301. package/docs/ja/specdojo/templates/opr-template.md +2 -4
  302. package/docs/ja/specdojo/templates/pm-organization-template.md +9 -3
  303. package/docs/ja/specdojo/templates/pm-plan-template.md +4 -4
  304. package/docs/ja/specdojo/templates/pm-quality-management-plan-template.md +17 -9
  305. package/docs/ja/specdojo/templates/pm-raci-template.md +24 -13
  306. package/docs/ja/specdojo/templates/pm-roles-template.yaml +3 -2
  307. package/docs/ja/specdojo/templates/prj-assumptions-constraints-dependencies-template.md +6 -3
  308. package/docs/ja/specdojo/templates/prj-comparison-of-alternatives-template.md +22 -19
  309. package/docs/ja/specdojo/templates/stsd-template.md +46 -21
  310. package/docs/ja/specdojo/templates/sysd-critical-flows-template.md +94 -0
  311. package/docs/ja/specdojo/templates/sysd-cross-cutting-policy-template.md +122 -0
  312. package/docs/ja/specdojo/templates/sysd-index-template.md +89 -0
  313. package/docs/specdojo/lib/yaml-metadata.cjs +7 -0
  314. package/docs/specdojo/schemas/v1/bdd.schema.yaml +25 -57
  315. package/docs/specdojo/schemas/v1/condense-records.schema.yaml +26 -0
  316. package/docs/specdojo/schemas/v1/dct.schema.yaml +10 -0
  317. package/docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml +3 -0
  318. package/docs/specdojo/schemas/v1/esil.schema.yaml +7 -141
  319. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +3 -0
  320. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +53 -3
  321. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +3 -0
  322. package/docs/specdojo/schemas/v1/exec-plan-frontmatter.schema.yaml +14 -0
  323. package/docs/specdojo/schemas/v1/exec-result-frontmatter.schema.yaml +18 -0
  324. package/docs/specdojo/schemas/v1/finding-cause.schema.yaml +22 -0
  325. package/docs/specdojo/schemas/v1/grade-pipeline-state.schema.yaml +1 -1
  326. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +2 -0
  327. package/docs/specdojo/schemas/v1/ifx-cmd.schema.yaml +65 -5
  328. package/docs/specdojo/schemas/v1/ifx-index.schema.yaml +142 -0
  329. package/docs/specdojo/schemas/v1/register-events.schema.yaml +2 -0
  330. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +17 -1
  331. package/package.json +2 -2
  332. package/templates/antigravity/orchestrator.md +3 -2
  333. package/templates/claude/agents/specdojo-orchestrator.md +3 -2
  334. package/templates/codex/agents/specdojo-orchestrator.toml +3 -2
  335. package/templates/codex/orchestrator.md +3 -2
  336. package/templates/devcontainer/tmux.conf +6 -0
  337. package/templates/opencode/agents/specdojo-orchestrator.md +3 -2
@@ -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,141 @@ specdojo:
17
17
 
18
18
  Glossary Documentation Rules
19
19
 
20
- 本ドキュメントは、業務分析・要求定義・設計・テストで参照する **用語集(Glossary)を YAML 形式で記述する標準ルール**です。
20
+ 業務分析・要求定義・設計・テストで参照する用語集を YAML 形式で記述するルールです。用語の意味と境界を定義し、利用者がガイドや画面・CLI で目にする言葉と対応付けます。
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
+ - 業務データ辞書やビジネスルールなどから参照する前に用語 ID を採番し、確定後は変更しない。
28
28
 
29
- ## 2. 位置づけと用語定義
29
+ ## 2. 位置づけ
30
30
 
31
- - 本用語集(Glossary)は、プロジェクト全体の SSOT(Single Source of Truth)としての役割を持つ。
32
- - 各種設計ドキュメントの `glossaryTermId` 等は、すべて本ルールで採番された `tm-...` ID を参照する。
31
+ - 用語の意味は用語集を正本とし、業務の判定条件、データ項目、操作手順、実装詳細はそれぞれの仕様・設計へ委ねる。
32
+ - 領域ごとの冒頭のコメントまたは代表用語の注記で、扱う範囲と共通・他領域の正本を示す。
33
+ - 共通メタ情報とリンク記法は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]]、配置は [[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-common.yaml`、`gl-sales.yaml`)。
40
+ - 同じ領域の翻訳版を併置するときは `gl-<対象領域>-<locale>.yaml` とし、ファイル名・用語集 ID で区別する(例: `gl-sales-ja.yaml`、`gl-sales-en.yaml`)。
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 は 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 は、接頭辞がなくても維持し、整形や領域分割を理由に改名しない。
46
48
 
47
49
  ## 4. 推奨 Frontmatter 項目
48
50
 
49
- YAML ファイルの先頭に、以下のメタデータ(ルートキー)を持たせることを推奨する。
51
+ YAML のメタ情報は `specdojo:` で包まずルートに置く。構造と値の制約は `docs/specdojo/schemas/v1/gl.schema.yaml` を正本とし、先頭の modeline から対応 schema を参照する。
50
52
 
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` | 任意 |
53
+ | 項目 | 説明 | 必須 |
54
+ | ---------- | -------------------------------------------- | ---- |
55
+ | `id` | 「ID規約」に従う用語集 ID | ○ |
56
+ | `type` | `glossary` 固定 | ○ |
57
+ | `rulebook` | `specdojo:gl-rulebook` | ○ |
58
+ | `title` | 対象領域が分かる用語集名 | ○ |
59
+ | `locale` | 定義の言語(例: `ja` / `en`) | ○ |
60
+ | `status` | 文書成熟度。`draft` / `ready` / `deprecated` | ○ |
61
+
62
+ `status` は schema 上は省略可能だが、共通メタ情報の規約に従って記載する。`ready` への昇格は人間が行う。
59
63
 
60
64
  ## 5. 本文要件
61
65
 
62
66
  ### 5.1. ルートキー要件
63
67
 
64
- - メタデータに加え、トップレベルに `terms`(配列)を必ず持つ。
68
+ - メタ情報に加え、ルートに `terms`(用語オブジェクトの配列)を必ず持つ。
69
+ - 掲載範囲の概念を識別できる用語を収録し、定義のない分類名や参照先を残さない。
70
+ - schema にないルートキーや用語のキーは追加しない。
65
71
 
66
72
  ### 5.2. `terms` の項目
67
73
 
68
74
  各用語の要素は以下のキーを持つ。
69
75
 
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 | 用例(短い例文) | 任意 |
76
+ | 項目 | 説明 | 必須 |
77
+ | -------------- | ------------------------------------------------------- | ---- |
78
+ | `id` | 用語を安定して識別する用語 ID | ○ |
79
+ | `term` | 利用者が目にする正式な呼び方 | ○ |
80
+ | `englishName` | 概念の英語名 | 任意 |
81
+ | `aliases` | 同じ概念の別名・従来表記の配列 | 任意 |
82
+ | `definition` | 意味と他の概念との境界が分かる定義 | ○ |
83
+ | `notes` | 読み手向けの前提・例外・使用文脈 | 任意 |
84
+ | `category` | 同じ用語集内で分類に使う用語 ID | 任意 |
85
+ | `relatedTerms` | 同じ用語集内の関連用語 ID の配列 | 任意 |
86
+ | `source` | 根拠文書へのリンク、schema のパス・定義名、URL など | 任意 |
87
+ | `status` | 用語の採用状態。`official` / `deprecated` / `candidate` | 任意 |
88
+ | `example` | 用語を使う短い例文 | 任意 |
89
+
90
+ 必須は `id`・`term`・`definition` の 3 項目とする。任意項目は説明に必要なものだけ記載し、用語の `status` とルートの文書成熟度を混同しない。
83
91
 
84
92
  ## 6. 記述ガイド
85
93
 
86
- ### 6.1. IDの命名推奨
94
+ ### 6.1. 全体方針・位置づけの判断
95
+
96
+ 利用者が概念を区別するために必要な語か、どの領域が意味の正本を持つかで収録先を決める。共通事項は「位置づけ」で示す上位標準を参照し、各領域へ再掲しない。
97
+
98
+ - 良い例: 販売と在庫の両方で使う「商品」は共通へ置き、販売固有の「つけ残高」は販売へ置く。
99
+ - 悪い例: 販売と在庫に同じ「商品」をそれぞれ定義し、更新時にどちらを直すか決まらない。
100
+
101
+ ### 6.2. ファイル命名・ID の判断
102
+
103
+ 新規 ID は領域と概念が読める英小文字の名詞を基本とし、略語は読み手に通じるものに限る。既存の確定 ID の維持を、新規の接頭辞規則より優先する。
104
+
105
+ - 良い例: 販売の新しい用語に `tm-sales-credit-limit` を採番し、既存の `tm-accounts-receivable` は維持する。
106
+ - 悪い例: 領域ごとに `tm-status` を新設する、または接頭辞をそろえるために確定済み ID を改名する。
107
+
108
+ ### 6.3. メタ情報・ルート構造の判断
109
+
110
+ `title` で対象領域、`locale` で定義の言語が分かり、メタ情報と `terms` が同じ階層にあるかを確認する。
111
+
112
+ - 良い例: `title: 用語集(販売)`、`locale: ja` とルートの `terms` を持つ。
113
+ - 悪い例: 全メタ情報を `specdojo:` の下に入れる、または `terms` を文章で代用する。
114
+
115
+ ### 6.4. 用語の見出し・英語名の判断
116
+
117
+ `term` はガイド・画面や CLI の表示・コマンド名で利用者が目にする言い方に合わせ、言い換えは `aliases` に置く。英語の用語と `englishName` は小文字にし、SpecDojo の概念名として大文字が定着したもの(Kata など)と固有名詞(SpecDojo など)だけを例外とする。別名として過去の表記を残すことは認める。
118
+
119
+ - 良い例: `term: つけ`、`englishName: sale on credit`、`aliases: [ツケ, 掛け売り]`。英語の見出しなら `term: job run` とする。
120
+ - 悪い例: 利用者が「つけ」と呼ぶものを `term: 売掛債権取引` とする、または `englishName: Sale On Credit` とする。
121
+
122
+ ### 6.5. 定義・注記・根拠の判断
123
+
124
+ `definition` は一文で意味と境界が分かる説明を基本とする。`notes` は前提・例外・使用文脈だけを補い、定義の繰り返しや、`category`・`relatedTerms` の指定方法など YAML の書き方を含めない。設定キーやコマンドとの対応は概念の理解に必要な範囲で示せるが、項目名の羅列を避け、独立して説明できる概念が増えたら用語を分ける。
125
+
126
+ - 良い例: つけの注記を「店主が認めた常連客だけが利用する。」とし、残高と限度額は別の用語にする。
127
+ - 悪い例: 「構成要素の `category` に本用語を指定する。」と注記する、または定義を「つけとはツケのこと。」で済ませる。
128
+ - schema の条件付き規則は、用語間の関係を短く説明し、条件分岐・必須キーの一覧は写さない。根拠は `source` に実在する文書のリンクや schema のパス・定義名で示す。
129
+ - 良い例: 「つけは常連客に認める後払いの販売で、つけ残高を管理する。」と関係を示し、厳密な条件は根拠へ委ねる。
130
+ - 悪い例: 注記へ schema の `if` / `then` と必須項目をそのまま転記する。
131
+ - 未確定の内容には共通ラベル(`_TODO_` / `_UNDECIDED_` / `_ASSUMPTION_`)を使い、確定時には解消する。
132
+
133
+ ### 6.6. 分類・関連用語の判断
87
134
 
88
- - `tm-` の命名は「名詞」を基本とする(例: `tm-reorder-point`)。
89
- - 略語を使う場合は、業務用語集で一般的に通じるものに限定し、必要なら `definition` に補足する。
135
+ ほかの用語の分類に使う概念も用語として定義し、`category` でまとめる。`relatedTerms` は同じ文脈で理解すべき用語に絞る。いずれも同じ用語集内の用語 ID だけを指定する。
90
136
 
91
- ### 6.2. 定義の書き方
137
+ - 良い例: 「販売」を定義して、同じファイルの「つけ」の `category` にその ID を指定する。
138
+ - 悪い例: 分類名を未定義の文字列にする、または共通用語を分類に使うためだけに領域別の用語集へ複製する。
139
+ - 領域をまたぐ関係は `notes` または `source` に正本の用語集への文書リンクと必要なら用語 ID を記し、`category`・`relatedTerms` には入れない。
140
+ - 良い例: 共通用語が別ファイルなら「商品の定義は共通用語集を参照する」と文書リンクで案内する。
141
+ - 悪い例: 別ファイルにしかない `tm-common-product` を `relatedTerms` に指定する。
142
+ - `validate:schema` はファイル内の用語 ID の重複と参照先の存在を検証する。用語集をまたぐ ID の一意性と同じ概念の重複定義は、別途横断で照合する。
92
143
 
93
- - 用語の定義は「一文で意味が通り、境界が分かる」ように書く。
94
- - 単なる同義語の羅列にならないようにし、他と区別できる条件を明記する。
95
- - 未確定事項や仮置き情報は、共通ラベル(`_TODO_` / `_UNDECIDED_` / `_ASSUMPTION_`)で記述する。
144
+ ### 6.7. 改訂・廃止時の判断
96
145
 
97
- ### 6.3. 関連用語と分類の運用
146
+ 意味の変更・廃止では、共通メタ情報標準の「文書の改訂・廃止とライフサイクル変更管理」に従い、BA が用語 ID を参照するデータ辞書・業務ルール・画面や CLI の用語を洗い出し、DEV が実装、QE がテスト・受入条件の追従を確認する。廃止・確定は PO が判断し、PM が移行作業を管理する。schema にない変更管理項目は YAML に増やさず、個票などの変更記録へ残す。
98
147
 
99
- - `relatedTerms` および `category` は、**同じ用語集の中に存在する用語ID(`tm-...`)** を指定する。
100
- - 関連が強い(同じ業務文脈でセットで出る)ものを中心にし、増やしすぎない。
101
- - 用語の参照関係は `validate:schema` の一環として検証される。存在しない ID への参照や、用語 ID の重複がある場合は検証エラーとなる。
148
+ - 良い例: 意味が変わる用語は新しい ID で定義し、旧用語は `status: deprecated` として後継を注記し、参照元を更新する。
149
+ - 悪い例: 旧 ID の定義を別の意味に上書きする、または参照元を確認せず用語を削除する。
102
150
 
103
151
  ## 7. 禁止事項
104
152
 
105
- - 用語IDを未採番のままにすること、または重複させること。
106
- - 用語IDを意味の違う用語に使い回すこと。
153
+ - 用語 ID を未採番・重複のままにすること、意味の違う用語に使い回すこと、確定後に変更すること。
107
154
  - `definition` を曖昧に書くこと(例: 「正しく処理される」「いい感じの在庫」など)。
108
- - 用語の説明に実装詳細(物理テーブル名、内部クラス名、SQL 等)を混ぜること。
109
- - 同じ概念を別名で重複登録し、`aliases` で統合しないこと。
110
- - 1 つのファイル内で言語を混在させること。
111
- - 章番号なし見出しを使用したり、章番号末尾の `.` を省略したりすること。
155
+ - 用語の説明へ物理テーブル名・内部クラス名・SQL 全文などの実装詳細や、仕様・schema の条件一覧を持ち込むこと。
156
+ - 同じ概念を別名・別領域で重複定義し、別名または正本への参照にまとめないこと。
157
+ - 読み手向けの意味を補わない編集手順・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,100 @@ 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 設定、コマンド構文は載せない。必要な詳細は技術構成・連携・運用の正本へ委ねる。
24
27
 
25
- - 物理構成(CIDR、IP、ポート、AZ)
26
- - スケーリング、冗長化、台数
27
- - セキュリティ設定(FW / SG / IAM)
28
- - 技術選定・製品名の詳細
28
+ ## 2. 位置づけと用語定義
29
29
 
30
- ## 1. 設計思想(最重要)
30
+ | 用語・文書 | 本書での意味・責務 |
31
+ | ------------------ | ------------------------------------------------------------------------------------------ |
32
+ | 実行環境 | ホスト・コンテナ・外部サービスなど、処理やデータを置く単位 |
33
+ | ネットワーク境界 | 到達経路・接続条件が変わる区切り。必ずしも物理ネットワークと一致しない |
34
+ | 論理ゾーン | 管理主体、公開範囲、情報の持ち出し条件を検討する区切り |
35
+ | 上位構成図 | 処理・データ・外部依存の責務を定義する入力。論理的なコンテナと実行用コンテナを同一視しない |
36
+ | 詳細設計・運用文書 | 接続設定、認証方式、監視閾値、復旧手順を管理する委譲先 |
31
37
 
32
- - Mermaid は図ではなく **「構造化テキスト」** として扱う。
33
- - 生成 AI は特に以下を **意味として解釈** する:
34
- - **ノード名**(役割)
35
- - **境界(subgraph)**(実行環境 / ネットワーク / ゾーン)
36
- - **矢印の方向**(入口 → 処理 → 永続化)
37
- - 見栄えは **配置・命名・色の一貫性** によって担保する。
38
+ ## 3. ファイル命名・ID規則
38
39
 
39
- 指針:**「装飾より構造」**
40
+ - ファイル名は `ifd-<target>.md` とし、対象システムまたは配置範囲を英小文字・数字・ハイフンで表す。
41
+ - `id` はファイル名の stem と対応させる。名前空間・配置の共通規則は [[specdojo:docs-structure-guide|ドキュメント構造ガイド]] を正とする。
42
+ - Mermaid のノード ID と表示名を分離する。文書内で一意な ID を使い、改訂時も同じ要素・経路の ID を維持する。
40
43
 
41
- ## 2. 図タイプ・方向の固定(必須)
44
+ ## 4. 推奨 Frontmatter 項目
42
45
 
43
- IFD は以下の形式に固定します。
46
+ 共通の値・構文は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] と成果物 Frontmatter schema を正とする。
44
47
 
45
- ````markdown
46
- ```mermaid
47
- flowchart LR
48
- ```
49
- ````
48
+ | 項目 | 扱い | IFD での用途 |
49
+ | ------------------------ | -------- | ---------------------------------------------------- |
50
+ | `id` / `type` / `status` | 必須 | 文書の識別、`architecture` 分類、成熟度 |
51
+ | `rulebook` | 必須 | `specdojo:ifd-mermaid-rulebook` を指定する |
52
+ | `owner` | 推奨 | 配置・境界設計を担うロール |
53
+ | `based_on` | 条件付き | 直接の根拠となる上位構成図。単なる参考文書は含めない |
54
+ | `part_of` / `supersedes` | 条件付き | 所属・置き換え関係がある場合に記載する |
50
55
 
51
- ### 2.1. 理由
56
+ ## 5. 本文要件
52
57
 
53
- - `flowchart LR` に固定することで **通信方向 = 左 → 右** が一貫し、生成AIが推論しやすくなる。
58
+ 見出し順・記入欄の骨組みは frontmatter で宣言した template を正本とする。以下は内容の成立条件であり、同じ表を全文書へ複製する指示ではない。
54
59
 
55
- ### 2.2. 禁止
60
+ | 内容 | 必須性 | 目的・判定条件 |
61
+ | ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
62
+ | 概要 | 必須 | 対象環境、図で判断すること、上位入力、対象外を識別できる |
63
+ | インフラ構成図 | 必須 | 実行場所、必要な境界、主要経路を Mermaid で示し、凡例で向き・線種・省略を説明する |
64
+ | 配置と境界の定義 | 必須 | 図中の要素に管理主体・保持情報・到達条件を対応付け、上位要素の配置または対象外の扱いを示す。代替配置がある場合は適用条件と置き換わる要素を区別する |
65
+ | 通信経路と情報の境界 | 必須 | 図と本文の経路 ID・起点・終点が対応し、目的、情報の要点、利用条件、詳細の正本または引き継ぎ先を追える |
66
+ | 技術前提・制約と検証観点 | 必須 | 隔離・認証・公開に関する前提と、境界別の障害影響・観測対象・主確認ロールを示す |
67
+ | メモ / 将来課題 | 条件付き | 仮定・未決事項がある場合、対象、影響、担当、解消条件・引き継ぎ先を残す |
56
68
 
57
- - `TB` / `RL` / `BT`
58
- - 図中での方向混在
69
+ ### 5.1. Mermaid の表現規約
59
70
 
60
- ## 3. 境界(subgraph)ルール(最大3階層)
71
+ - `flowchart LR` を使う。矢印の意味は依頼・参照・転送などの主たる起点から終点への向きとし、通常の応答は同じ線に含める。独立した逆方向の起動だけを別線にする。
72
+ - `subgraph` は最大 3 階層とする。実行環境・ネットワーク・論理ゾーンのうち必要な境界だけを描き、各枠が何の区切りか明記する。階層数を埋めるための枠は作らない。
73
+ - 表示名は役割を主語とする。配置や接続先の識別に必要な製品名は「推論サービス(製品名)」のように補記してよい。製品名だけで責務を表さない。
74
+ - 処理は矩形、DB は円筒、ファイル保管は角丸を基本とする。形状・色・絵文字だけに意味を持たせず文字で識別できるようにする。
75
+ - 経路ラベルに ID と通信目的を付ける。プロトコル名だけのラベルは使わない。線種を分ける場合は凡例で意味を定義する。
76
+ - 中継を省略して論理的な経路を一本で描く場合は、図の近傍で省略した中継と到達条件を説明する。中継方式が未確定なら仮定とし、直接接続が許可されている図と誤読させない。
77
+ - 装飾は任意とし、色を使う場合は `classDef` で役割の分類を統一する。交差が判断を妨げる場合は範囲を分割し、共有要素と経路 ID を対応付ける。
61
78
 
62
- 境界は **最大3階層** までとし、意味を固定します。
79
+ ## 6. 記述ガイド
63
80
 
64
- | レベル | 意味 | 例 |
65
- | ------ | ------------ | ----------------------- |
66
- | Lv1 | 実行環境 | Cloud / On-Prem / SaaS |
67
- | Lv2 | ネットワーク | VPC / Project / Segment |
68
- | Lv3 | 論理ゾーン | Public / Private |
81
+ 共通のメタ情報・リンク記法は上位標準を正本とし、本章では IFD 固有の判断だけを扱う。
69
82
 
70
- ### 3.1. 例
83
+ ### 6.1. 概要
71
84
 
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
- ```
85
+ 対象環境と判断範囲を先に選ぶ。良い例は「店舗端末から共有サービスまでの到達範囲を示し、通信不能時の切り分けに使う」。悪い例は「システム全体を説明する」で、配置判断の範囲が選べない。
83
86
 
84
- ### 3.2. 禁止
87
+ ### 6.2. インフラ構成図
85
88
 
86
- - Lv4 以上の subgraph
87
- - Subnet CIDR、AZ 名、IP、ポート番号などの物理情報
88
- - 業務概念(例:Order Management)を境界名に使うこと
89
+ 枠を越えるごとに実行場所・接続条件・管理主体のどれが変わるかで描き分ける。良い例は「店舗端末と外部保管サービスを別枠にし、送信する記録をラベルにする」。悪い例は「同じ製品なので外部サービスも端末の枠に入れる」。仮の経路は図の近傍にも仮定と記す。入口の中継を省略するなら「入口経由の記録要求を論理線で表す」と注記し、端末から内部サービスへ直接到達できるように描かない。
89
90
 
90
- ## 4. ノード命名規約(最重要)
91
+ ### 6.3. 配置と境界の定義
91
92
 
92
- ### 4.1. 表示名は「役割名」で統一する
93
+ 配置表では図にない管理責務・保持情報を補う。推奨列は「図中の環境・要素、上位要素、管理主体、情報・到達条件」。良い例は「作業記録は端末側、外部には送信対象だけを渡す案」。悪い例は「Private 枠なので安全」で、アクセス制御の根拠がない。
93
94
 
94
- - 表示名は **役割(Role)** を表す
95
- - 製品名 / サービス名 / 略語は使用しない
96
- - 英語・単数形を基本とする
95
+ 代替配置は同時稼働か選択肢かを判断し、後者なら置き換え後の保持範囲・到達性を確認対象にする。良い例は「コンテナ実行の代わりにホストで同じ役割を実行し、書込範囲を再確認する」。悪い例は「両環境に同名の処理を置き、稼働条件を示さない」。上位の責務は配置を変えても引き継ぐ。
97
96
 
98
- #### 4.1.1. OK
97
+ ### 6.4. 通信経路と情報の境界
99
98
 
100
- - `Load Balancer`
101
- - `Web App`
102
- - `API Server`
103
- - `Relational Database`
104
- - `Object Storage`
105
- - `Cache`
106
- - `Message Queue`
99
+ 条件付きの外部依存を常時必須の経路と混ぜない。推奨列は「経路 ID、起点 → 終点、目的・情報、利用条件・詳細の委譲先」。良い例は「共有時だけ控えを外部へ送り、接続・認証の契約は連携仕様で定める」。悪い例は「全データを同期する」で、情報範囲と正本の位置が不明である。
107
100
 
108
- #### 4.1.2. NG
101
+ ### 6.5. 技術前提・制約と検証観点
109
102
 
110
- - `ALB`
111
- - `EC2`
112
- - `Cloud Run`
113
- - `RDS`
114
- - `Redis` / `Kafka`(※技術選定は別ドキュメント)
103
+ 境界が成立する条件と、条件が崩れたときに観測するものを結ぶ。良い例は「別ホストへの到達不能、サービスの応答欠落、記録の保存失敗を分けて観測する」。悪い例は「トンネルがつながるので作業も成功する」。検証設計への入力と実施済みの証跡を区別し、監視対象は識別するが、閾値や復旧コマンドを再定義しない。
115
104
 
116
- ### 4.2. 絵文字アイコン(任意)
105
+ ### 6.6. メモ / 将来課題
117
106
 
118
- 絵文字は **人間の視認性向上** には有効ですが、表示差や幅崩れが起きる環境もあるため、次のルールで運用します。
107
+ 不明点が承認・検証・運用のどこを止めるかで影響を具体化する。良い例は「公開先未決。ARC が到達範囲を整理し、PO の公開判断後に配置へ反映する」。悪い例は「後で検討する」。単なる調査待ちと仮定は共通ラベルで区別する。
119
108
 
120
- - 絵文字は **任意**(なくても成立する)
121
- - 絵文字は **表示名(Label)のみに付ける**(IDには付けない)
122
- - **1ノード1個まで**、表示名の **先頭に付ける**
123
- - 絵文字だけに頼らず、必ず役割名テキストも併記する
109
+ ## 7. 禁止事項
124
110
 
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
- - 矢印の過剰な交差(読みづらくなった場合は境界整理または図を分割する)
111
+ - 上位図の責務を変更したり、業務判断・公開可否・製品採択を根拠なく確定したりしない。
112
+ - 論理ゾーンやトンネルの存在だけから、隔離・認証・情報非保持を保証しない。
113
+ - 詳細設定・schema・リファレンスの値、構文、構造を複製しない。秘密値や個人固有の接続先を載せない。
114
+ - 完成図の例を本書に埋め込まない。対応する型の所在は frontmatter の宣言で管理する。
115
+ - 改訂・廃止で経路や境界が変わる場合、追従先を省略しない。ARC が上位構成図・連携設計、QE が検証対象、OPS が監視・運用参照、PO が公開判断への影響を確認する。ライフサイクル手続きは共通メタ情報標準に従う。