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
@@ -3,310 +3,169 @@ specdojo:
3
3
  id: specdojo:cxd-rulebook
4
4
  type: rulebook
5
5
  deliverable_type: architecture
6
- status: draft
7
- recipe: undecided
6
+ status: ready
7
+ target_format: markdown
8
+ includes:
9
+ - specdojo:cxd-mermaid-rulebook
10
+ recipe: specdojo:cxd-recipe
8
11
  sample: specdojo:cxd-sample
9
- template: undecided
12
+ template: specdojo:cxd-template
13
+ based_on:
14
+ - specdojo:rulebook-authoring-standard
10
15
  ---
11
16
 
12
- # C4コンテキスト図 ドキュメント作成ルール
17
+ # C4コンテキスト図(CXD)作成ルール
13
18
 
14
- C4 Contextual Diagram (CXD) Documentation Rules
19
+ C4 Context Diagram (CXD) Authoring Rule
15
20
 
16
- 本ドキュメントは、アーキテクチャ設計のために **C4コンテキスト図と、その図を説明する文章**を、統一した粒度・表現で作成するためのルールです。
17
-
18
- この章の成果物は、次の2つをセットで扱います。
19
-
20
- - **C4コンテキスト図(Mermaid)**: 対象システムと「境界外」の人・外部システムとの関係を俯瞰で合意する
21
- - **説明(Markdown)**: 図の要素(人/対象/外部/境界/関係)の意味を文章で合意する
22
-
23
- Mermaid 記法そのもののルールは [cxd-mermaid-rulebook.md](cxd-mermaid-rulebook.md) を参照してください。
21
+ 対象システムを単一のブラックボックスとして捉え、境界外の利用者・外部システムとの関係と責任分界を定義します。境界の合意、外部依存の識別、境界上の技術制約と検証観点を扱います。
24
22
 
25
23
  ## 1. 全体方針
26
24
 
27
- - CXDは「対象システムが、誰に/何と関わるか」を合意するための図である。
28
- - 図に入れるのは **システム境界の外側との関係**までとし、内部構造(コンテナ/コンポーネント)や実装詳細は含めない。
29
- - 1つの図には **対象システムを1つ**だけ置く(複数対象がある場合は図を分ける)。
30
- - 図は「正確さ(過剰な詳細)」よりも「解釈が割れないこと(合意)」を優先する。
31
-
32
- ## 2. ファイル命名・ID規則
33
-
34
- - ファイル名: `cxd-<番号>-<短い日本語名>.md`
35
-
36
- - 例: `cxd-010-駄菓子屋きぬや販売管理システム-コンテキスト.md`
37
-
38
- - Frontmatter:
39
-
40
- - `id`: 小文字ハイフン形式(例: `cxd-candy-shop-sales-context`)
41
- - `title`: 「〇〇のC4コンテキスト図」のように対象が分かる表現
42
-
43
- ## 3. 推奨 Frontmatter 項目
44
-
45
- Frontmatter の共通ルールは [document-metadata-standard.md](../standards/document-metadata-standard.md) に従います。
46
-
47
- | 項目 | 説明 | 必須 |
48
- | ---------- | ---------------------------------------------- | ---- |
49
- | id | ドキュメントID(小文字ハイフン) | ○ |
50
- | type | `architecture` 固定 | ○ |
51
- | title | ドキュメント名 | ○ |
52
- | status | `draft`/`ready`/`deprecated` | ○ |
53
- | part_of | 上位ドキュメントID(分割している場合) | 任意 |
54
- | based_on | 根拠となる定義(用語集、外部IF、上位方針など) | 任意 |
55
- | supersedes | 置き換え関係(古い図→新しい図) | 任意 |
56
-
57
- ### 3.1. `based_on` の考え方(例)
58
-
59
- - 用語集(`gl-...`)や業務データ辞書(`bdd-...`)
60
- - 外部システムIFの仕様(IF章のドキュメント)
61
- - 参照する上位の方針(DEC、非機能要件など)
62
-
63
- ## 4. CXDで合意すること(スコープ)
64
-
65
- ### 4.1. 合意したいこと
66
-
67
- - 対象システムの名前と、責務の一言(何をするシステムか)
68
- - 利用者(Person)と、その利用目的(何のために使うか)
69
- - 外部システム(External Software System)と、連携の意図(何をやり取りするか)
70
- - 関係(Relationship)の向きと意味(誰が主に呼び出す/依存するか)
71
- - 対象システムの「境界」の考え方(何を含み、何を含まないか)
72
-
73
- ### 4.2. 合意しないこと(この図で扱わない)
74
-
75
- - 対象システムの内部の分解(コンテナ/コンポーネント、内部プロセス、内部データストア)
76
- - APIエンドポイント、HTTPメソッド、リクエスト/レスポンスJSONなどのIF詳細
77
- - 物理テーブル名・物理カラム名・SQL全文
78
- - 実装クラス/関数名、ライブラリ名、具体的な技術選定の列挙
79
-
80
- ## 5. CXDの要素定義(図と文章の両方で説明する)
81
-
82
- この章では、図に描いた要素について **最低限の説明**を併記し、レビュー可能にします。
25
+ - 1 ファイルにつき対象システム(または合意したシステム境界)を 1 つ扱い、内部構造は展開しません。
26
+ - 利用者と外部システム、主たる利用・連携の関係を、図と対応表で解釈が割れない粒度で記述します。
27
+ - 図の描画記法は `includes` で宣言した [[specdojo:cxd-mermaid-rulebook|Mermaid を用いたC4コンテキスト図 作成ルール]] に従います。図と本文の表で要素名・関係ラベルを一致させ、図の矢印を文章でそのままなぞる重複説明は行いません。
28
+ - 詳細の委譲先は「正本の選び方と参照の境界」に従い、CXD には境界判断に必要な要点と参照先だけを残します。
29
+ - 未作成の参照先や未確定の境界論点は、確定仕様と分けて「メモ / 将来課題」に記録します。
30
+ - **共通の運用**: 役割の割り当ては適用先のメンバー定義に、`status`・承認・改訂と廃止・未決事項の引き継ぎは [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従います。文書の整形・lint はリポジトリの検証で扱い、業務の受入確認には含めません。
83
31
 
84
- ### 5.1. Person(人/ロール)
32
+ ### 1.1. 対象者と確認する内容
85
33
 
86
- Personは、対象システムに対して目的をもって関わる主体(人/役割/組織)です。
34
+ | 対象者 | 解決する課題 | 確認する内容 |
35
+ | ---------------------------- | -------------------------------------- | ---------------------------------------------- |
36
+ | 価値・対象範囲を確認する読者 | 業務とシステムの責務がずれる | 境界の内外、委譲先、利用者・外部連携の妥当性 |
37
+ | 設計・開発に用いる読者 | 下位設計の前提が曖昧になる | 依存方向、信頼・実行境界、詳細の正本 |
38
+ | 品質・運用を確認する読者 | 外部依存の障害時に確認対象が分からない | 境界上の入出力、異常時の扱い、テスト・監視対象 |
87
39
 
88
- - 書くこと(推奨):
89
- - ロール名(例: 店員、店主、経理担当)
90
- - 対象システムに何をしに来るか(例: 売上登録を行う、在庫を確認する)
91
- - 重要な前提(ある場合のみ。例: 店舗内からのみ利用)
92
- - 書かないこと:
93
- - 個人名、組織の詳細階層、UI操作手順の逐語列挙
40
+ この表は文書の読者の確認観点を示します。直接のシステム利用者は「Person(人・ロール)」で定義します。
94
41
 
95
- ### 5.2. Software System(対象システム)
42
+ ## 2. 位置づけと用語定義
96
43
 
97
- この図の中心に置くシステムです。CXDでは **対象システムは1つ**に限定します。
44
+ CXD は利用目的と対象範囲を根拠として、アーキテクチャ設計の最上位でシステム全体の境界と外部関係を定義します。下図の入力文書は候補であり、実際の根拠は各タスクの参照範囲に従います。
98
45
 
99
- - 書くこと(推奨):
100
- - システム名(短く一意)
101
- - システムの責務(1文。例: 店舗の販売・仕入・在庫・簡易会計を一元管理する)
102
- - 「境界」に含める範囲の補足(ある場合のみ)
103
- - 書かないこと:
104
- - 内部モジュール/サブシステムの列挙、画面一覧、DBスキーマ
105
-
106
- ### 5.3. External Software System(外部システム)
107
-
108
- 対象システムの外側にあり、対象システムが連携する相手(既存の別システム、SaaS、決済、会計など)です。
109
-
110
- - 書くこと(推奨):
111
- - 外部システム名(一般名でよい)
112
- - 連携の目的(例: 決済を依頼する、仕訳を送る、マスタを参照する)
113
- - 連携の方向性(誰が主に呼び出す/依存するか)
114
- - 書かないこと:
115
- - API仕様の詳細、データ項目一覧(それらはIF仕様へ)
116
-
117
- ### 5.4. System Boundary(システム境界)
118
-
119
- 境界は「対象システムが責任を持つ範囲」を表します。境界の内外が曖昧だと、責任分界(運用・障害・変更)が曖昧になります。
120
-
121
- - 書くこと(推奨):
122
- - 境界に含めるもの(例: 店舗内の販売管理)
123
- - 境界に含めないもの(例: 決済そのもの、会計システムの処理)
124
- - 注意:
125
- - 境界内に「対象システムのノード1つだけ」を置く運用を基本とし、内部構造は別図(コンテナ図など)へ委譲します。
126
-
127
- ### 5.5. Relationship(関係)
128
-
129
- 関係は「やり取りの意味」を合意するための線です。CXDでは **すべての関係にラベル**を付けます。
130
-
131
- - 書くこと(必須):
132
- - 方向(誰が主に利用/依存/送信するか)
133
- - ラベル(短い日本語。名詞句または短い動詞句)
134
- - 書くこと(推奨):
135
- - やり取りの意図(例: 売上登録、決済依頼、仕訳連携)
136
- - 重要な前提(ある場合のみ。例: 非同期、日次バッチ)
137
- - 書かないこと:
138
- - HTTP詳細、データ項目列挙、SQL、実装条件式
139
-
140
- ## 6. 本文構成(標準テンプレ)
141
-
142
- 各 CXD 成果物は、以下見出しを順番に並べます。
143
-
144
- 1. 概要
145
- 2. C4コンテキスト図(Mermaid)
146
- 3. 要素の説明
147
- 4. 補足
46
+ ```mermaid
47
+ graph TD
48
+ BIZ["プロジェクト概要 / 概念データフロー<br/>(prj-overview / cdfd)"] --> CXD["C4コンテキスト図 (cxd)<br/>システム境界・利用者・外部システム・関係"]
49
+ CXD -.->|"内部構造の展開"| C4LOW["下位C4・インフラ図<br/>(cnd / cpd / ifd)"]
50
+ CXD -.->|"操作・連携契約の正本参照"| IF["UI・CLI仕様 / 外部IF仕様<br/>(uis / clis / ifx-*)"]
51
+ CXD -.->|"採用技術の正本参照"| TSD["技術スタック一覧<br/>(tsd-index / tsd-*)"]
52
+ ```
148
53
 
149
- ## 7. 記述ガイド詳細
54
+ 要素の意味と選定基準は「要素と境界の定義」に集約します。
150
55
 
151
- ### 7.1. 概要
56
+ ## 3. ファイル命名・ID規則
152
57
 
153
- - 「この図が何を表すか」「対象システム」「前提」を1〜3文で書きます。
58
+ 命名と配置の共通原則は [[specdojo:docs-structure-guide|ドキュメント構成ガイド]] および [[specdojo:id-and-file-naming-standard|ID・ファイル命名標準]] に従います。
154
59
 
155
- ### 7.2. C4コンテキスト図(Mermaid)
60
+ - 配置先は原則として `docs/<lang>/product/030-architecture/010-c4/` とします。
61
+ - ファイル名は `cxd-<context>.md` とします(例: `cxd-specdojo.md`)。`<context>` は対象システムまたは対象コンテキストを表す英小文字・数字・ハイフンのケバブケースとします。
62
+ - プロダクト文書の ID は `cxd-<context>`、プロジェクト文書は `<project-id>:cxd-<context>` とします。同梱の完成例は成果物と衝突しない `specdojo:` の ID を使います。
63
+ - 文書名は本文先頭の H1 に記述し、対象システム名と C4 コンテキスト図であることを明示します。
156
64
 
157
- - Mermaid のコードブロックで図を記述します。
158
- - Mermaid 記法ルールは [cxd-mermaid-rulebook.md](cxd-mermaid-rulebook.md) に従います。
159
- - 図には、少なくとも以下を含めます。
160
- - Person(人/ロール)
161
- - 対象システム(Software System)
162
- - 外部システム(External Software System)
163
- - 関係(Relationship。全矢印にラベル)
65
+ ## 4. 推奨 Frontmatter 項目
164
66
 
165
- ### 7.3. 要素の説明
67
+ 共通の必須・任意項目と値・型の制約は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] および `docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml` を正本とします。CXD 固有の指定と根拠の選び方は次のとおりです。
166
68
 
167
- - 図に登場する要素を、レビューしやすい粒度で説明します。
168
- - 推奨スタイル:
169
- - `###` レベルの小見出しで要素名(人/対象/外部/境界/関係)
170
- - 1〜3文で意味・前提・境界条件(含む/含まない)を説明
69
+ - `type` は本 rulebook の `deliverable_type` に対応する `architecture`、`rulebook` は `specdojo:cxd-rulebook` とします。
70
+ - `part_of` は所属する上位アーキテクチャ文書や索引がある場合に記載し、`based_on` は成果物カタログの `depends_on` の推移閉包に含まれる直接の内容根拠だけを示します。プロジェクト共通文脈(`prj-overview` 等)が `depends_on` にない場合は `based_on` に含めず、本文中で参照します。
71
+ - 未作成の依存先や未確定の契約は「メモ / 将来課題」へ記録し、空の `based_on` を埋めるために無関係な ID を追加しません。
171
72
 
172
- ### 7.4. 補足
73
+ ## 5. 本文要件
173
74
 
174
- - 未確定な外部連携、境界が揺れている論点、図を分ける必要がありそうな論点を列挙します。
75
+ 見出し順・表・記入欄の骨組みは frontmatter で宣言した template を正本とし、本章は各内容の目的と必須性を定義します。
175
76
 
176
- ## 8. 命名・記述スタイル
77
+ | 章 | 必須・任意 | 目的と内容要件 |
78
+ | --------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------ |
79
+ | 概要 | 必須 | 対象システムの目的・提供価値、コンテキスト図の対象範囲と対象外、主要ステークホルダーと確認内容を 1〜3 文と表で示す |
80
+ | C4コンテキスト図(Mermaid) | 必須 | `specdojo:cxd-mermaid-rulebook` に準拠したコンテキスト図と、図の読み取りに必要な補足注記(1〜3 文)を示す |
81
+ | 要素と境界の定義 | 必須 | 対象システムとシステム境界、Person、External Software System、Relationship を表で定義し、詳細仕様の正本へ案内する |
82
+ | 技術前提・制約と検証観点 | 必須 | システム境界における技術前提・制約(実行形態、信頼境界、外部依存の前提)と、境界・外部依存のテスト・検証観点を示す |
83
+ | メモ / 将来課題 | 任意 | 未作成の参照先、未確定の境界論点、段階的拡張予定について、論点・影響・解消条件を示す。該当事項があれば必須 |
177
84
 
178
- - 用語はこの図の中で揺らさない(同じ相手を別名で呼ばない)。
179
- - ラベルは短くし、長い場合は改行(`<br>`)で読みやすくする(詳細はIF仕様へ)。
180
- - Personは「役割」を優先し、個人名ではなくロール名にする。
85
+ ## 6. 記述ガイド
181
86
 
182
- ## 9. 禁止事項
87
+ 各章の判断基準と対比例を示します。
183
88
 
184
- 次の記述は、CXDの粒度を超えるため避けます。
89
+ ### 6.1. 概要
185
90
 
186
- | 項目 | 理由 |
187
- | ------------------------------------------- | --------------------------------- |
188
- | 物理テーブル名・物理カラム名・SQL全文 | 図の粒度を超える(DB設計に記述) |
189
- | APIエンドポイント/HTTP/JSON等の詳細 | IF仕様に記述する |
190
- | 実装クラス/関数名、技術スタック列挙 | 変更に弱い・合意の対象がずれる |
191
- | 対象システム内部の詳細プロセス/データストア | コンテナ図/コンポーネント図で表す |
192
- | 矢印ラベルなしの関係 | 何の関係か合意できない |
91
+ - 判断基準: 対象システムが誰の何の課題を解決し、どこまでを本図の対象範囲とし、何を下位図や別仕様へ委ねるかを読み取れること。また、主要ステークホルダーが本図で確認・合意する観点が対応付けられていること。
92
+ - 良い例: 「本図は販売管理 CLI を単一のシステム境界として捉え、店舗スタッフ・管理者および外部の印刷・会計基盤との関係を定義する。コンテナ内部のモジュール構成は `cnd`、コマンド構文は `clis` を参照する。」
93
+ - 悪い例: 「本図はシステムの全体像を示すコンテキスト図である。」対象範囲と委譲先が分かりません。
193
94
 
194
- ## 10. レビュー観点(チェックリスト)
95
+ ### 6.2. C4コンテキスト図(Mermaid)
195
96
 
196
- - 対象システムは1つに絞れているか
197
- - PersonとExternal Software Systemが含まれているか(無い場合は理由が書かれているか)
198
- - すべての関係にラベルがあり、意味が解釈一致するか
199
- - 境界の内外が説明され、責任分界が曖昧でないか
200
- - 図が「内部設計」や「IF詳細」に踏み込んでいないか
97
+ - 判断基準: `includes` で宣言した記法に従い、対象システムが一つで、境界外の主体とすべての関係を識別できること。ノード形状・色・構文は記法ルールへ委ねます。外部システムや Person がない場合は、その理由を明記します。
98
+ - 図の直後には、矢印の向きの意味(主たる利用・起動・データ送信の方向)、応答の省略、複数の依存をまとめた表示など、読み取りに必要な注記を 1〜3 文で補足します。詳細の参照先は関係表に集約し、図の矢印を 1 本ずつ文章で書き直す説明は置きません。
99
+ - 良い例: 境界内に対象システム 1 ノードのみを置き、Person と外部システムからの入出力・呼び出しを短い動詞句または名詞句ラベル(例: `売上登録・集計指示`、`AI実行起動・結果取得`)で表現する。
100
+ - 悪い例: 境界内に DB テーブルや内部モジュールを並べたり、ラベルなしの矢印やエンドポイント URL を図中に書き込んだりする。
201
101
 
202
- ## 11. サンプル(簡易)
102
+ ### 6.3. 要素と境界の定義
203
103
 
204
- ### 11.1. メタ情報(Frontmatter)
104
+ 判断基準は、図に登場するすべての要素と関係が漏れ・表記揺れなく表で定義され、境界内外の責任分界と詳細仕様の正本を追えることです。名称・ラベルは図との照合に使い、表には責務・利用条件・障害時の影響など図にない判断情報を加えます。
205
105
 
206
- ```yaml
207
- ---
208
- id: cxd-candy-shop-sales-context
209
- type: architecture
210
- title: 駄菓子屋きぬや販売管理システムのC4コンテキスト図
211
- status: draft
212
- part_of: []
213
- based_on: []
214
- ---
215
- ```
106
+ #### 6.3.1. 対象システムとシステム境界
216
107
 
217
- ### 11.2. 概要
108
+ - 対象システムの「システム名」「提供する中核責務」「境界内に含める範囲」「境界外へ委ねる範囲(対象外と委譲先)」を表または項目で明記します。
109
+ - 良い例: 「境界内: 取引記録とレシート控えの保持。境界外: プリンタの物理制御(印刷基盤へ委譲)、現金授受(店番担当が実施)。」
110
+ - 悪い例: 「販売管理に関する機能一式を提供する。」自システムと委譲先の責務が分かりません。
218
111
 
219
- この図は「駄菓子屋きぬや販売管理システム」が、利用者と外部システムとどのように関わるかを俯瞰します。
112
+ #### 6.3.2. Person(人・ロール)
220
113
 
221
- ### 11.3. C4コンテキスト図(Mermaid)
114
+ - 推奨列は「Person(図中ラベル)」「対応ロール」「利用目的・主な関わり」「境界上の接点・確認責務」です。直接の利用・運用・管理の接点を持つ業務上の利用者区分と対応させます。
115
+ - 良い例: 「店番担当: 現金販売を記録する。会計・印字の状態を確認し、保留取引を店舗責任者へ渡す。」業務上の利用者区分を用い、プロジェクトの役職を直接利用者として機械的に列挙しません。
116
+ - 悪い例: 「ユーザー: システムを使う人。」ロールごとの利用目的や境界上の確認責務が分かりません。
222
117
 
223
- ```mermaid
224
- flowchart LR
225
- %% Person
226
- 店員["👤店員"]
227
- 店主["👤店主"]
228
-
229
- %% External Systems
230
- 会計システム["会計システム"]
231
- 決済サービス["決済サービス"]
232
-
233
- %% Target System Boundary
234
- subgraph 境界["対象システム"]
235
- 販売管理システム("駄菓子屋きぬや<br>販売管理システム")
236
- end
237
-
238
- %% Relationships
239
- 店員 -->|"売上登録"| 販売管理システム
240
- 店主 -->|"商品・在庫管理"| 販売管理システム
241
- 販売管理システム -->|"会計仕訳連携"| 会計システム
242
- 販売管理システム -->|"決済依頼"| 決済サービス
243
- 決済サービス -->|"決済結果"| 販売管理システム
244
-
245
- %% Styles
246
- classDef person fill:#fff3bf,stroke:#f08c00,color:#000;
247
- classDef system fill:#d0ebff,stroke:#1c7ed6,color:#000;
248
- classDef external fill:#e9ecef,stroke:#495057,color:#000;
249
- class 店員,店主 person;
250
- class 販売管理システム system;
251
- class 会計システム,決済サービス external;
252
- style 境界 fill:#ffffff,fill-opacity:0,stroke:#868e96,stroke-width:1px,stroke-dasharray: 5 5;
253
- ```
118
+ #### 6.3.3. External Software System(外部システム)
254
119
 
255
- ```plaintext
256
- flowchart LR
257
- %% Person
258
- 店員["👤店員"]
259
- 店主["👤店主"]
260
-
261
- %% External Systems
262
- 会計システム["会計システム"]
263
- 決済サービス["決済サービス"]
264
-
265
- %% Target System Boundary
266
- subgraph 境界["対象システム"]
267
- 販売管理システム("駄菓子屋きぬや<br>販売管理システム")
268
-
269
- end
270
-
271
- %% Relationships
272
- 店員 -->|"売上登録"| 販売管理システム
273
- 店主 -->|"商品・在庫管理"| 販売管理システム
274
- 販売管理システム -->|"会計仕訳連携"| 会計システム
275
- 販売管理システム -->|"決済依頼"| 決済サービス
276
- 決済サービス -->|"決済結果"| 販売管理システム
277
-
278
- %% Styles
279
- classDef person fill:#fff3bf,stroke:#f08c00,color:#000;
280
- classDef system fill:#d0ebff,stroke:#1c7ed6,color:#000;
281
- classDef external fill:#e9ecef,stroke:#495057,color:#000;
282
- class 店員,店主 person;
283
- class 販売管理システム system;
284
- class 会計システム,決済サービス external;
285
- style 境界 fill:#ffffff,fill-opacity:0,stroke:#868e96,stroke-width:1px,stroke-dasharray: 5 5;
286
- ```
120
+ - 推奨列は「外部システム(図中ラベル)」「区分・位置づけ」「対象システムとの責任分界」「不在・障害時の影響と扱い」です。
121
+ - 確認できた連携相手を列挙し、必須の依存と機能を選んだ場合だけ使う依存を区別します。同じ端末で動く外部 CLI も責務が別なら境界外とし、未確認の接続経路や障害時の保証は仮定または論点として示します。
122
+ - 複数の外部システムを一つのノードにまとめる場合も、利用条件・責務・障害の影響は区別します。例えばローカル履歴管理とリモート共有をまとめても、通信失敗がローカル操作をすべて停止させるとは扱いません。注記と表で違いを説明できない場合はノードを分けます。
123
+ - 良い例: 「印刷基盤: 対象システムから控えを受け取って物理印字を担う。会計記録の管理は対象システムに残す。」復旧保証は確認済みの連携契約に限ります。
124
+ - 悪い例: 「外部サービス: データを連携する。」委譲範囲と障害の影響が分かりません。
287
125
 
288
- ### 11.4. 要素の説明
126
+ #### 6.3.4. Relationship(関係・連携契約)
289
127
 
290
- #### 11.4.1. Person(人/ロール)
128
+ - 推奨列は「関係ID」「起点 → 終点」「図中ラベル」「やり取りする情報・制御の要点」「連携方式・境界」「正本・関連仕様」です。
129
+ - 図の全矢印と対応付け、起動・参照する主体と方向、詳細仕様の正本(`clis`、`ifx-cmd`、`ifx-api`、`ifx-file` 等)を示します。
130
+ - 良い例: 「`REL-03`: 対象システム → 印刷基盤。印字依頼と結果をやり取りし、詳細は外部コマンド連携仕様を参照する。」目的・方向・詳細の更新先が分かります。
131
+ - 悪い例: 引数フラグの全一覧や JSON ペイロードの全フィールドを表に転載する。詳細の正本との二重管理になります。
291
132
 
292
- 店員・店主が、販売登録や在庫・商品管理のために対象システムを利用します。
133
+ #### 6.3.5. 正本の選び方と参照の境界
293
134
 
294
- #### 11.4.2. 対象システム(Software System)
135
+ | 対象 | 中身を委ねる正本 | CXD に残す判断情報 |
136
+ | ---------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------ |
137
+ | システム内部のコンテナ・モジュール | C4 コンテナ図(`cnd`)・C4 コンポーネント図(`cpd`) | 対象システム全体としての責務と外部との境界 |
138
+ | 実行環境・ネットワーク配置 | インフラ構成図(`ifd`) | 境界をまたぐ通信・実行形態の前提(ローカル実行、外部通信等) |
139
+ | 採用技術・ランタイム・バージョン | 技術スタック一覧(`tsd-index`)・個別技術定義(`tsd`) | アーキテクチャ境界に影響する技術上の前提のみ |
140
+ | 利用者の画面操作・CLI 操作 | 画面仕様(`uis`)・CLI 仕様(`clis`) | 誰がどの目的で対象システムを操作するか |
141
+ | 外部システムとの連携契約 | 外部インターフェース仕様(`ifx-index` / `ifx-*`) | 連携の目的、方向、渡す情報の概要、不在・失敗時の境界上の扱い |
295
142
 
296
- 店舗の販売・仕入・在庫に関する情報を一元管理し、会計・決済などの外部連携を行います。
143
+ - 未作成の正本については、必要な境界・契約と影響を「メモ / 将来課題」に記録します。
144
+ - 判断基準: CXD だけで境界を説明でき、値・構文・構造の詳細には固有の更新先があること。良い例は「連携目的を残して電文は IF 仕様へ委ねる」、悪い例は「正本へのリンクだけを置き、責任分界を省く」です。
297
145
 
298
- #### 11.4.3. 外部システム(External Software System)
146
+ ### 6.4. 技術前提・制約と検証観点
299
147
 
300
- 会計システムへは仕訳相当情報を連携し、決済サービスへは決済を依頼して結果を受信します(詳細はIF仕様に記載)。
148
+ - 判断基準: システム境界の成立に必要な技術的前提・制約(実行環境、ネットワーク到達性、認証・秘密情報の管理境界、人間による承認ゲート等)が明示され、かつ境界・外部依存に対するテスト・受入観点が識別できること。
149
+ - 「技術前提・制約」と「システム境界・外部依存の検証観点」の 2 つの小節(または表)に分け、検証観点を関係 ID または対象境界に対応付けます。検証設計へ渡す確認事項と、契約・実装で確認済みの保証を区別します。
150
+ - 良い例: 「外部コマンドの時間切れ時に、会計結果と印字結果を区別できるか確認する。認証管理者と外部へ渡す情報は連携契約で確認する。」検証対象と確認済みの保証を区別します。
151
+ - 悪い例: 「セキュリティに配慮し、十分にテストを行う。」具体的な制約と検証対象が分かりません。
301
152
 
302
- #### 11.4.4. 境界(System Boundary)
153
+ ### 6.5. メモ / 将来課題
303
154
 
304
- 境界には販売管理システム本体を含みます。決済処理や会計処理そのものは境界の外側です。
155
+ - 判断基準: 確定仕様と未作成の下位文書・未確定の外部連携を区別し、論点・影響範囲・解消条件を示すこと。仮定の宣言は該当する境界定義に置き、ここでは見直す条件と影響する境界・関係を示します。
156
+ - 良い例: 「印字結果不明時の再印刷条件は未確定で、二重印字の恐れがある。照合・再印刷の条件を定め、会計を再実行せず紙面を照合できることを確認して解消する。」
157
+ - 悪い例: 「詳細は別途検討する。」どの境界に影響し、何を確認すれば解消するか判断できません。
305
158
 
306
- ### 11.5. 補足
159
+ ## 7. 禁止事項
307
160
 
308
- - 会計連携の頻度(リアルタイム/日次)を確定する。
161
+ | 禁止する記述 | 理由 |
162
+ | --------------------------------------------------------------- | ------------------------------------------------------------------- |
163
+ | 内部コンテナ・内部モジュール・物理 DB テーブルの図中への混入 | C4 コンテキスト図の粒度を超え、`cnd`・`cpd`・`dts` の責務と重なる |
164
+ | コマンド引数・API エンドポイント・JSON ペイロード詳細の本文転載 | `clis`・`ifx-*`・リファレンス等の正本との二重管理を防ぐ(PJR-2GD6) |
165
+ | ラベルのない関係矢印、または図と表の間の要素名・ラベルの不一致 | ステークホルダー間でシステム境界と連携内容の合意が取れなくなる |
309
166
 
310
- ## 12. 参照
167
+ ## 8. 運用ルール
311
168
 
312
- - Mermaid 記法(CXD): [cxd-mermaid-rulebook.md](../rulebooks/cxd-mermaid-rulebook.md)
169
+ - システム境界、対象ロール、外部システムの種類・連携方向、境界上の制約や検証観点が変わる場合は CXD を改訂します。外部コマンドのオプション追加や内部モジュール分割のみの変更は各正本(`clis`・`ifx-*`・`cnd` 等)へ反映し、CXD の境界定義に影響がないことを確認します。
170
+ - 境界を展開する `cnd`・`cpd`・`ifd`、利用者の接点を定義する `uis`・`clis`、外部連携の `ifx-*`、境界テスト・受入条件を CXD 固有の整合確認先とします。
171
+ - 受入確認では、利用目的から Person・関係・委譲先をたどり、外部依存の不在・失敗・結果不明の場合を照合します。図と表が対応し、責任分界、詳細の更新先、確認対象と期待結果を特定でき、未確認の保証を断定していなければ合格とします。