specdojo 0.6.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 (366) hide show
  1. package/.github/agents/specdojo-orchestrator.md +3 -2
  2. package/CHANGELOG.md +193 -0
  3. package/README.md +2 -2
  4. package/dist/catalog/build.js +24 -1
  5. package/dist/catalog/plan.js +1 -1
  6. package/dist/catalog/scaffold.js +4 -1
  7. package/dist/commands/agent.js +33 -0
  8. package/dist/commands/init.js +6 -1
  9. package/dist/commands/night-orchestrator.js +6 -4
  10. package/dist/commands/orchestrator.js +10 -1
  11. package/dist/dashboard/dashboard-timeline.js +18 -16
  12. package/dist/dashboard/dashboard.js +612 -259
  13. package/dist/dashboard/epic-plan.js +81 -0
  14. package/dist/dashboard/exec-records.js +16 -20
  15. package/dist/dashboard/routines.js +8 -6
  16. package/dist/dashboard/timeline-build.js +5 -9
  17. package/dist/dashboard/timeline.js +9 -4
  18. package/dist/devcontainer/command.js +18 -0
  19. package/dist/devcontainer/host-script.js +21 -0
  20. package/dist/devcontainer/scaffold.js +22 -3
  21. package/dist/docs/frontmatter-namespace.js +1 -48
  22. package/dist/docs/yaml-pages.js +125 -3
  23. package/dist/exec/agent-config.js +22 -0
  24. package/dist/exec/agent-plan.js +3 -2
  25. package/dist/exec/antigravity-session.js +154 -0
  26. package/dist/exec/commands.js +69 -21
  27. package/dist/exec/commit-hook-skips.js +78 -0
  28. package/dist/exec/core.js +19 -7
  29. package/dist/exec/events.js +159 -8
  30. package/dist/exec/evidence.js +64 -16
  31. package/dist/exec/handoff.js +9 -13
  32. package/dist/exec/limit.js +1 -1
  33. package/dist/exec/mechanical-result.js +45 -0
  34. package/dist/exec/migrate-records.js +249 -0
  35. package/dist/exec/parent-validation.js +160 -12
  36. package/dist/exec/pipeline-state.js +27 -5
  37. package/dist/exec/plan-markdownlint.js +89 -0
  38. package/dist/exec/plans-condense-findings.js +89 -0
  39. package/dist/exec/plans-core.js +24 -17
  40. package/dist/exec/plans-generation.js +52 -25
  41. package/dist/exec/plans-grade-findings.js +8 -3
  42. package/dist/exec/plans-kata-findings.js +61 -0
  43. package/dist/exec/plans-planning.js +3 -3
  44. package/dist/exec/plans-storage.js +12 -24
  45. package/dist/exec/register-resume.js +69 -42
  46. package/dist/exec/register.js +26 -22
  47. package/dist/exec/repo-integration-sync.js +8 -4
  48. package/dist/exec/repo-integration.js +21 -1
  49. package/dist/exec/reporter.js +121 -23
  50. package/dist/exec/results.js +85 -24
  51. package/dist/exec/review-completion.js +47 -0
  52. package/dist/exec/review-kata.js +109 -0
  53. package/dist/exec/run/agent-pipeline.js +75 -6
  54. package/dist/exec/run/agent.js +20 -7
  55. package/dist/exec/run/in-place.js +69 -32
  56. package/dist/exec/run/job.js +81 -24
  57. package/dist/exec/run/lifecycle-commands.js +264 -43
  58. package/dist/exec/run/mode-shared.js +11 -3
  59. package/dist/exec/run/register-command.js +12 -10
  60. package/dist/exec/run/register-core.js +20 -13
  61. package/dist/exec/run/register-mode.js +12 -12
  62. package/dist/exec/run/register-post-review.js +21 -9
  63. package/dist/exec/run/register-resume.js +28 -18
  64. package/dist/exec/run/register-state.js +10 -7
  65. package/dist/exec/run/register-worktree.js +60 -30
  66. package/dist/exec/run/schedule-mode.js +26 -6
  67. package/dist/exec/run/schedule-prepare.js +228 -45
  68. package/dist/exec/run/schedule-task.js +132 -25
  69. package/dist/exec/run/shared.js +4 -3
  70. package/dist/exec/run/trailing-records.js +35 -0
  71. package/dist/exec/run-records.js +2 -0
  72. package/dist/exec/strategy.js +1 -0
  73. package/dist/exec/trailing-records.js +242 -0
  74. package/dist/exec/trial-commands.js +3 -2
  75. package/dist/exec/validate-records-commit.js +110 -0
  76. package/dist/exec/validate-records.js +148 -0
  77. package/dist/exec/worktree-command.js +29 -16
  78. package/dist/exec/worktree-ops-commit.js +118 -59
  79. package/dist/exec/worktree-ops-lifecycle.js +77 -44
  80. package/dist/exec/worktree-ops-merge.js +13 -2
  81. package/dist/exec/worktree-ops.js +2 -2
  82. package/dist/exec/worktree.js +19 -2
  83. package/dist/grade/apply.js +32 -6
  84. package/dist/grade/command-inspect.js +2 -2
  85. package/dist/grade/command-run.js +2 -0
  86. package/dist/grade/command-shared.js +1 -1
  87. package/dist/grade/core.js +18 -5
  88. package/dist/grade/markdown.js +3 -3
  89. package/dist/grade/pipeline-state.js +15 -11
  90. package/dist/grade/plan.js +37 -17
  91. package/dist/grade/result.js +3 -3
  92. package/dist/grade/run.js +23 -3
  93. package/dist/grade/target-discovery.js +17 -4
  94. package/dist/grade/targets.js +12 -11
  95. package/dist/job/job.js +31 -17
  96. package/dist/job/noop.js +104 -0
  97. package/dist/register/core.js +2 -0
  98. package/dist/register/create-commands.js +28 -3
  99. package/dist/register/deliverable-target.js +9 -1
  100. package/dist/register/epic.js +104 -26
  101. package/dist/register/event-merge.js +3 -0
  102. package/dist/register/events.js +4 -0
  103. package/dist/register/external-project.js +3 -0
  104. package/dist/register/item.js +6 -0
  105. package/dist/register/maintenance-commands.js +4 -1
  106. package/dist/register/planning.js +7 -14
  107. package/dist/register/register.js +74 -32
  108. package/dist/register/track-domains.js +34 -0
  109. package/dist/register/track-plan.js +78 -0
  110. package/dist/register/transition-commands.js +8 -0
  111. package/dist/register/work-table.js +64 -0
  112. package/dist/review/grade.js +35 -13
  113. package/dist/routine/definition.js +4 -3
  114. package/dist/routine/failure.js +30 -0
  115. package/dist/routine/routine.js +56 -32
  116. package/dist/routine/storage.js +33 -0
  117. package/dist/schedule/schedule.js +1 -0
  118. package/dist/schedule/strategy-generate-document.js +26 -14
  119. package/dist/schedule/strategy-generate-scope.js +17 -45
  120. package/dist/schedule/strategy-generate.js +33 -3
  121. package/dist/schedule/strategy-profiles.js +86 -12
  122. package/dist/shared/agent-types.js +2 -0
  123. package/dist/shared/condense-records.js +25 -0
  124. package/dist/shared/deprecation.js +8 -0
  125. package/dist/shared/document-metadata.js +20 -0
  126. package/dist/shared/finding-cause.js +20 -0
  127. package/dist/shared/frontmatter-namespace.js +48 -0
  128. package/dist/shared/git.js +149 -15
  129. package/dist/shared/grade-result.js +17 -1
  130. package/dist/shared/local-state.js +20 -0
  131. package/dist/shared/markdownlint-config.js +8 -3
  132. package/dist/shared/plan-conventions.js +129 -0
  133. package/dist/shared/plan-templates.js +57 -41
  134. package/dist/shared/provider-scaffold.js +2 -0
  135. package/dist/shared/run-records.js +224 -0
  136. package/dist/shared/specdojo-config.js +39 -21
  137. package/dist/shared/specdojo-gitignore.js +1 -0
  138. package/dist/shared/text.js +65 -5
  139. package/dist/shared/timeline-index.js +2 -0
  140. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +11 -2
  141. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +4 -74
  142. package/docs/ja/specdojo/exec-templates/xep-condense-template.md +50 -0
  143. package/docs/ja/specdojo/exec-templates/xep-draft-template.md +17 -5
  144. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +16 -3
  145. package/docs/ja/specdojo/exec-templates/xep-recipe-guided-template.md +15 -5
  146. package/docs/ja/specdojo/exec-templates/xep-recipe-maintenance-template.md +6 -0
  147. package/docs/ja/specdojo/exec-templates/xep-register-template.md +1 -1
  148. package/docs/ja/specdojo/exec-templates/xep-rulebook-maintenance-template.md +6 -0
  149. package/docs/ja/specdojo/exec-templates/xep-sample-maintenance-template.md +6 -0
  150. package/docs/ja/specdojo/exec-templates/xep-template-maintenance-template.md +6 -0
  151. package/docs/ja/specdojo/exec-templates/xer-condense-template.md +25 -0
  152. package/docs/ja/specdojo/exec-templates/xp-common-conventions-template.md +50 -0
  153. package/docs/ja/specdojo/exec-templates/xrp-common-conventions-template.md +30 -0
  154. package/docs/ja/specdojo/guides/branch-workflow-guide.md +1 -1
  155. package/docs/ja/specdojo/guides/docs-editing-guide.md +48 -0
  156. package/docs/ja/specdojo/guides/docs-structure-guide.md +48 -15
  157. package/docs/ja/specdojo/guides/exec-config-guide.md +61 -28
  158. package/docs/ja/specdojo/guides/exec-operation-guide.md +61 -13
  159. package/docs/ja/specdojo/guides/exec-worktree-guide.md +20 -11
  160. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +4 -2
  161. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +92 -55
  162. package/docs/ja/specdojo/guides/project-move-guide.md +381 -0
  163. package/docs/ja/specdojo/guides/quick-start-guide.md +589 -807
  164. package/docs/ja/specdojo/guides/register-operation-guide.md +26 -4
  165. package/docs/ja/specdojo/guides/remote-host-development-guide.md +33 -4
  166. package/docs/ja/specdojo/guides/review-guide.md +22 -19
  167. package/docs/ja/specdojo/guides/routine-operation-guide.md +14 -8
  168. package/docs/ja/specdojo/guides/ryu-guide.md +23 -13
  169. package/docs/ja/specdojo/guides/schedule-design-guide.md +7 -4
  170. package/docs/ja/specdojo/guides/schedule-operation-guide.md +41 -3
  171. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +5 -4
  172. package/docs/ja/specdojo/guides/timeline-design-guide.md +27 -144
  173. package/docs/ja/specdojo/guides/use-case-guide.md +471 -74
  174. package/docs/ja/specdojo/recipes/bac-recipe.md +94 -0
  175. package/docs/ja/specdojo/recipes/bes-recipe.md +105 -0
  176. package/docs/ja/specdojo/recipes/br-recipe.md +84 -0
  177. package/docs/ja/specdojo/recipes/cdfd-overview-recipe.md +88 -86
  178. package/docs/ja/specdojo/recipes/cdfd-uc-recipe.md +108 -122
  179. package/docs/ja/specdojo/recipes/cnd-recipe.md +125 -0
  180. package/docs/ja/specdojo/recipes/cpd-recipe.md +126 -0
  181. package/docs/ja/specdojo/recipes/cxd-recipe.md +145 -0
  182. package/docs/ja/specdojo/recipes/ifd-recipe.md +134 -0
  183. package/docs/ja/specdojo/recipes/ifx-cmd-recipe.md +135 -86
  184. package/docs/ja/specdojo/recipes/ifx-index-recipe.md +130 -0
  185. package/docs/ja/specdojo/recipes/pm-organization-recipe.md +29 -26
  186. package/docs/ja/specdojo/recipes/pm-plan-recipe.md +35 -26
  187. package/docs/ja/specdojo/recipes/pm-quality-management-plan-recipe.md +38 -28
  188. package/docs/ja/specdojo/recipes/pm-raci-recipe.md +39 -31
  189. package/docs/ja/specdojo/recipes/pm-roles-recipe.md +26 -28
  190. package/docs/ja/specdojo/recipes/prj-assumptions-constraints-dependencies-recipe.md +10 -8
  191. package/docs/ja/specdojo/recipes/prj-comparison-of-alternatives-recipe.md +18 -17
  192. package/docs/ja/specdojo/recipes/stsd-recipe.md +100 -62
  193. package/docs/ja/specdojo/recipes/sysd-critical-flows-recipe.md +106 -0
  194. package/docs/ja/specdojo/recipes/sysd-cross-cutting-policy-recipe.md +137 -0
  195. package/docs/ja/specdojo/recipes/sysd-index-recipe.md +122 -0
  196. package/docs/ja/specdojo/references/command-reference.md +146 -99
  197. package/docs/ja/specdojo/references/deliverables-reference.md +9 -4
  198. package/docs/ja/specdojo/references/directory-layout-reference.md +3 -2
  199. package/docs/ja/specdojo/references/specdojo-config-reference.md +17 -16
  200. package/docs/ja/specdojo/rulebooks/bac-rulebook.md +72 -290
  201. package/docs/ja/specdojo/rulebooks/bdd-rulebook.md +212 -79
  202. package/docs/ja/specdojo/rulebooks/bds-rulebook.md +138 -154
  203. package/docs/ja/specdojo/rulebooks/bes-index-rulebook.md +147 -59
  204. package/docs/ja/specdojo/rulebooks/bes-rulebook.md +100 -96
  205. package/docs/ja/specdojo/rulebooks/br-rulebook.md +88 -108
  206. package/docs/ja/specdojo/rulebooks/ccd-mermaid-rulebook.md +126 -211
  207. package/docs/ja/specdojo/rulebooks/cdfd-d2-rulebook.md +367 -0
  208. package/docs/ja/specdojo/rulebooks/cdfd-mermaid-rulebook.md +6 -5
  209. package/docs/ja/specdojo/rulebooks/cdfd-overview-rulebook.md +96 -100
  210. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +38 -47
  211. package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +132 -106
  212. package/docs/ja/specdojo/rulebooks/cdsd-rulebook.md +102 -68
  213. package/docs/ja/specdojo/rulebooks/cdt-rulebook.md +152 -0
  214. package/docs/ja/specdojo/rulebooks/cld-rulebook.md +9 -184
  215. package/docs/ja/specdojo/rulebooks/clis-rulebook.md +187 -0
  216. package/docs/ja/specdojo/rulebooks/cnd-rulebook.md +93 -247
  217. package/docs/ja/specdojo/rulebooks/cpd-rulebook.md +104 -241
  218. package/docs/ja/specdojo/rulebooks/cxd-rulebook.md +124 -257
  219. package/docs/ja/specdojo/rulebooks/dct-index-rulebook.md +87 -98
  220. package/docs/ja/specdojo/rulebooks/dct-rulebook.md +9 -7
  221. package/docs/ja/specdojo/rulebooks/dec-rulebook.md +2 -1
  222. package/docs/ja/specdojo/rulebooks/dss-rulebook.md +193 -0
  223. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +100 -54
  224. package/docs/ja/specdojo/rulebooks/ifd-mermaid-rulebook.md +69 -252
  225. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +91 -76
  226. package/docs/ja/specdojo/rulebooks/ifx-file-rulebook.md +252 -226
  227. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +118 -40
  228. package/docs/ja/specdojo/rulebooks/imp-business-rulebook.md +11 -11
  229. package/docs/ja/specdojo/rulebooks/imp-data-rulebook.md +9 -9
  230. package/docs/ja/specdojo/rulebooks/imp-interface-rulebook.md +4 -4
  231. package/docs/ja/specdojo/rulebooks/imp-operations-rulebook.md +11 -11
  232. package/docs/ja/specdojo/rulebooks/imp-test-rulebook.md +11 -11
  233. package/docs/ja/specdojo/rulebooks/mm-rulebook.md +4 -3
  234. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +34 -29
  235. package/docs/ja/specdojo/rulebooks/pm-change-request-log-rulebook.md +8 -8
  236. package/docs/ja/specdojo/rulebooks/pm-issue-log-rulebook.md +2 -2
  237. package/docs/ja/specdojo/rulebooks/pm-organization-rulebook.md +50 -56
  238. package/docs/ja/specdojo/rulebooks/pm-plan-rulebook.md +46 -55
  239. package/docs/ja/specdojo/rulebooks/pm-quality-management-plan-rulebook.md +57 -54
  240. package/docs/ja/specdojo/rulebooks/pm-raci-rulebook.md +50 -65
  241. package/docs/ja/specdojo/rulebooks/pm-risk-register-rulebook.md +2 -2
  242. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +70 -97
  243. package/docs/ja/specdojo/rulebooks/pr-rulebook.md +2 -1
  244. package/docs/ja/specdojo/rulebooks/prj-assumptions-constraints-dependencies-rulebook.md +47 -56
  245. package/docs/ja/specdojo/rulebooks/prj-comparison-of-alternatives-rulebook.md +61 -135
  246. package/docs/ja/specdojo/rulebooks/sf-index-rulebook.md +116 -32
  247. package/docs/ja/specdojo/rulebooks/sf-rulebook.md +118 -61
  248. package/docs/ja/specdojo/rulebooks/sld-rulebook.md +152 -57
  249. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +51 -39
  250. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +101 -46
  251. package/docs/ja/specdojo/rulebooks/sysd-critical-flows-rulebook.md +72 -329
  252. package/docs/ja/specdojo/rulebooks/sysd-cross-cutting-policy-rulebook.md +74 -263
  253. package/docs/ja/specdojo/rulebooks/sysd-index-rulebook.md +78 -195
  254. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +4 -9
  255. package/docs/ja/specdojo/rulebooks/trc-requirements-to-specs-rulebook.md +3 -4
  256. package/docs/ja/specdojo/rulebooks/trc-requirements-to-tests-rulebook.md +3 -3
  257. package/docs/ja/specdojo/rulebooks/uis-rulebook.md +140 -143
  258. package/docs/ja/specdojo/samples/bac-sample.md +106 -21
  259. package/docs/ja/specdojo/samples/bdd-sample.yaml +143 -35
  260. package/docs/ja/specdojo/samples/bds-sample.md +100 -21
  261. package/docs/ja/specdojo/samples/bes-index-sample.md +59 -20
  262. package/docs/ja/specdojo/samples/bes-sample.md +80 -21
  263. package/docs/ja/specdojo/samples/br-sample.md +68 -14
  264. package/docs/ja/specdojo/samples/ccd-sample.md +81 -19
  265. package/docs/ja/specdojo/samples/cdfd-overview-sample.md +248 -140
  266. package/docs/ja/specdojo/samples/cdfd-sample.md +172 -99
  267. package/docs/ja/specdojo/samples/cdfd-uc-sample.md +130 -97
  268. package/docs/ja/specdojo/samples/cdsd-sample.md +89 -20
  269. package/docs/ja/specdojo/samples/cdt-sample.md +116 -0
  270. package/docs/ja/specdojo/samples/cld-sample.md +3 -30
  271. package/docs/ja/specdojo/samples/clis-sample.md +132 -0
  272. package/docs/ja/specdojo/samples/cnd-sample.md +127 -21
  273. package/docs/ja/specdojo/samples/cpd-sample.md +136 -22
  274. package/docs/ja/specdojo/samples/cxd-sample.md +108 -22
  275. package/docs/ja/specdojo/samples/dct-index-sample.yaml +63 -17
  276. package/docs/ja/specdojo/samples/dss-sample.md +175 -0
  277. package/docs/ja/specdojo/samples/gl-sample.yaml +50 -14
  278. package/docs/ja/specdojo/samples/ifd-sample.md +105 -21
  279. package/docs/ja/specdojo/samples/ifx-cmd-sample.yaml +91 -60
  280. package/docs/ja/specdojo/samples/ifx-file-sample.md +462 -21
  281. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +87 -19
  282. package/docs/ja/specdojo/samples/pm-members-sample.yaml +37 -13
  283. package/docs/ja/specdojo/samples/pm-organization-sample.md +52 -20
  284. package/docs/ja/specdojo/samples/pm-plan-sample.md +84 -26
  285. package/docs/ja/specdojo/samples/pm-quality-management-plan-sample.md +55 -22
  286. package/docs/ja/specdojo/samples/pm-raci-sample.md +69 -28
  287. package/docs/ja/specdojo/samples/pm-roles-sample.yaml +13 -12
  288. package/docs/ja/specdojo/samples/prj-assumptions-constraints-dependencies-sample.md +50 -26
  289. package/docs/ja/specdojo/samples/prj-comparison-of-alternatives-sample.md +89 -62
  290. package/docs/ja/specdojo/samples/sf-index-sample.md +89 -20
  291. package/docs/ja/specdojo/samples/sf-sample.md +121 -21
  292. package/docs/ja/specdojo/samples/sld-sample.md +107 -21
  293. package/docs/ja/specdojo/samples/stsd-sample.md +54 -26
  294. package/docs/ja/specdojo/samples/sysd-critical-flows-sample.md +166 -21
  295. package/docs/ja/specdojo/samples/sysd-cross-cutting-policy-sample.md +178 -21
  296. package/docs/ja/specdojo/samples/sysd-index-sample.md +82 -21
  297. package/docs/ja/specdojo/samples/tml-sample.yaml +4 -1
  298. package/docs/ja/specdojo/samples/uis-sample.md +164 -20
  299. package/docs/ja/specdojo/standards/document-metadata-standard.md +33 -4
  300. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +3 -1
  301. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +1 -0
  302. package/docs/ja/specdojo/templates/bac-template.md +76 -0
  303. package/docs/ja/specdojo/templates/bes-template.md +56 -0
  304. package/docs/ja/specdojo/templates/br-template.md +64 -0
  305. package/docs/ja/specdojo/templates/cdfd-overview-template.md +161 -83
  306. package/docs/ja/specdojo/templates/cdfd-template.md +81 -54
  307. package/docs/ja/specdojo/templates/cdfd-uc-template.md +130 -89
  308. package/docs/ja/specdojo/templates/cnd-template.md +137 -0
  309. package/docs/ja/specdojo/templates/cpd-template.md +129 -0
  310. package/docs/ja/specdojo/templates/cxd-template.md +105 -0
  311. package/docs/ja/specdojo/templates/dct-data-model-cdt-template.yaml +40 -0
  312. package/docs/ja/specdojo/templates/dct-data-model-cld-template.yaml +7 -14
  313. package/docs/ja/specdojo/templates/dct-index-template.md +9 -20
  314. package/docs/ja/specdojo/templates/dct-project-management-template.yaml +5 -1
  315. package/docs/ja/specdojo/templates/ifd-template.md +86 -0
  316. package/docs/ja/specdojo/templates/ifx-cmd-template.yaml +44 -28
  317. package/docs/ja/specdojo/templates/ifx-index-template.yaml +40 -0
  318. package/docs/ja/specdojo/templates/opr-template.md +2 -4
  319. package/docs/ja/specdojo/templates/pm-organization-template.md +9 -3
  320. package/docs/ja/specdojo/templates/pm-plan-template.md +4 -4
  321. package/docs/ja/specdojo/templates/pm-quality-management-plan-template.md +17 -9
  322. package/docs/ja/specdojo/templates/pm-raci-template.md +24 -13
  323. package/docs/ja/specdojo/templates/pm-roles-template.yaml +3 -2
  324. package/docs/ja/specdojo/templates/prj-assumptions-constraints-dependencies-template.md +6 -3
  325. package/docs/ja/specdojo/templates/prj-comparison-of-alternatives-template.md +22 -19
  326. package/docs/ja/specdojo/templates/stsd-template.md +46 -21
  327. package/docs/ja/specdojo/templates/sysd-critical-flows-template.md +94 -0
  328. package/docs/ja/specdojo/templates/sysd-cross-cutting-policy-template.md +122 -0
  329. package/docs/ja/specdojo/templates/sysd-index-template.md +89 -0
  330. package/docs/specdojo/lib/yaml-metadata.cjs +7 -0
  331. package/docs/specdojo/schemas/v1/bdd.schema.yaml +25 -57
  332. package/docs/specdojo/schemas/v1/condense-records.schema.yaml +26 -0
  333. package/docs/specdojo/schemas/v1/dct.schema.yaml +10 -0
  334. package/docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml +3 -0
  335. package/docs/specdojo/schemas/v1/esil.schema.yaml +7 -141
  336. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +3 -0
  337. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +54 -3
  338. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +3 -0
  339. package/docs/specdojo/schemas/v1/exec-plan-frontmatter.schema.yaml +14 -0
  340. package/docs/specdojo/schemas/v1/exec-result-frontmatter.schema.yaml +18 -0
  341. package/docs/specdojo/schemas/v1/finding-cause.schema.yaml +22 -0
  342. package/docs/specdojo/schemas/v1/grade-pipeline-state.schema.yaml +1 -1
  343. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +2 -0
  344. package/docs/specdojo/schemas/v1/ifx-cmd.schema.yaml +65 -5
  345. package/docs/specdojo/schemas/v1/ifx-index.schema.yaml +142 -0
  346. package/docs/specdojo/schemas/v1/register-events.schema.yaml +2 -0
  347. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +17 -1
  348. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +1 -0
  349. package/package.json +6 -3
  350. package/templates/antigravity/README.md +19 -46
  351. package/templates/antigravity/exec-defaults-snippet.yaml +5 -6
  352. package/templates/antigravity/orchestrator.md +3 -2
  353. package/templates/antigravity/settings.edit.json +73 -0
  354. package/templates/antigravity/settings.orchestrator.json +15 -0
  355. package/templates/antigravity/settings.report.json +7 -0
  356. package/templates/antigravity/settings.review.json +7 -0
  357. package/templates/claude/agents/specdojo-orchestrator.md +3 -2
  358. package/templates/codex/agents/specdojo-orchestrator.toml +3 -2
  359. package/templates/codex/orchestrator.md +3 -2
  360. package/templates/devcontainer/remote-host/devcontainer-tmux.sh +217 -0
  361. package/templates/devcontainer/remote-host/specdojo-tmux.sh.sample +8 -96
  362. package/templates/devcontainer/remote-host/ssh-config.sample +3 -1
  363. package/templates/devcontainer/tmux.conf +6 -0
  364. package/templates/init-agent-members.yaml +1 -0
  365. package/templates/init-exec-defaults.yaml +1 -1
  366. package/templates/opencode/agents/specdojo-orchestrator.md +3 -2
@@ -3,7 +3,7 @@ specdojo:
3
3
  id: specdojo:bdd-rulebook
4
4
  type: rulebook
5
5
  deliverable_type: data
6
- status: draft
6
+ status: ready
7
7
  target_format: yaml
8
8
  recipe: not-needed
9
9
  sample: specdojo:bdd-sample
@@ -14,122 +14,255 @@ specdojo:
14
14
 
15
15
  Business Data Dictionary (BDD) Documentation Rules
16
16
 
17
- 本ドキュメントは、業務分析・要求定義・システム設計のために **業務データ辞書を記述する標準ルール**です。
18
- 業務上の管理単位(エンティティ)とその属性(項目)の論理名・物理名・説明・制約などを定義します。
19
- データの意味や構造に関する共通理解を関係者間で図り、システム設計や実装の基礎情報として活用します。
17
+ 業務データ辞書(BDD)で、業務上の管理単位と項目の意味を記述するための基準を定めます。
20
18
 
21
19
  ## 1. 全体方針
22
20
 
23
- - 業務分析・要求定義・設計で共通利用する業務データ辞書を、YAMLで統一的に定義する。
24
- - 業務上の管理単位(エンティティ)と属性(フィールド)の意味・制約・例値を、判断可能な粒度で記述する。
25
- - 実装詳細の仕様書ではなく、業務概念とデータ定義の共通理解を形成するための基準文書として扱う。
21
+ - **適用範囲**: 業務分析・要求定義・設計で利用する `bdd-*.yaml` を対象とする。
22
+ - **実装重複の排除**: 実装詳細を再掲するのではなく、schema や実装(TypeScript 型)が存在するエンティティはそれらを正本として参照し、業務データ辞書にはスキーマから読み取れない業務上の意味(項目の業務的定義、enum 値が表す業務状態など)に特化して記述する。
23
+ - **完成条件**: 「本文要件」を満たし、「成果物の検証手順」の機械検証と手動照合をともに完了する。コマンドの成功だけで業務上の正しさを判定しない。
24
+ - **確定条件**: BDD の `status: ready` への昇格は PO・BA・ARC・DEV・QE の確認を経て人間が判断する。本 rulebook 自体の昇格には、さらに「rulebook 改訂候補の enum 網羅確認」の対象別証跡を必要とする。agent は `draft` のまま編集する。
25
+ - **変更時の影響範囲**: BDD の検証スキーマ、成果物カタログ、参照するスキーマ・型定義、用語集、CCD、状態・業務ルールの正本を確認する。正本の変更と業務注釈の整合を別々に確認する。
26
26
 
27
27
  ## 2. 位置づけと用語定義
28
28
 
29
- - 本ルールは `type: data` の成果物に適用する。
30
- - `logical_name` は業務利用者が理解できる論理名、`physical_name` はDB列互換の物理名を指す。
31
- - `glossary_term_id` は用語集との参照キー、`related_terms` は関連用語への補助参照を指す。
29
+ - **成果物の種別**: 本ルールは `type: data` の成果物に適用する(成果物メタデータとしての `type` は `data` 固定であり、各フィールドのデータ型を表す `type` と区別する)。
30
+ - **機械検証正本との依存関係**: YAML の構造・型・正規表現の正本は `docs/specdojo/schemas/v1/bdd.schema.yaml` とする。本書は各キーの用途と業務上の判断を扱い、構文の詳細はスキーマを参照する。
31
+ - **共通規約の正本**: メタ情報は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]]、配置・命名は [[specdojo:docs-structure-guide|ドキュメント構成ガイド]] に従い、共通事項を BDD ごとに再掲しない。
32
+ - **主要な関係者(Role code)と確認観点**:
33
+ - **BA(ビジネスアナリスト / 主作成者)**: 業務上の管理単位・フィールドの業務的意味・状態定義の正確性と完全性を記述する(`vp-ba-requirements-completeness`)。
34
+ - **PO(プロダクトオーナー / 確認者)**: 業務概念のスコープ、エンティティ境界、業務用語の整合性を確認・承認する(`vp-po-purpose-alignment`, `vp-po-decision-readiness`)。
35
+ - **ARC(アーキテクト / 確認者・利用者)**: システム設計・データ構造・正本スキーマ参照(`schema_ref`)との整合性、技術制約を確認する(`vp-arc-technical-constraints`)。
36
+ - **DEV(開発者 / 利用者)**: 実装(モデル・型定義・テーブル設計)の基礎情報として参照し、TypeScript 型参照(`type_ref`)やスキーマとの対応を確認する(`vp-dev-implementation-readiness`)。
37
+ - **QE(品質保証 / 確認者)**: 制約条件、許容値、検証可能性を確認する(`vp-qe-verifiability`)。
38
+ - **用語定義**:
39
+ - **エンティティ(entities)**: 業務上の独立した管理単位・データオブジェクト。
40
+ - **フィールド(fields)**: エンティティを構成する個々のデータ項目。
41
+ - **論理名(`logical_name`)**: 業務利用者が直感的に理解できる日本語名称(単数形)。
42
+ - **物理名(`physical_name`)**: DB 列名やシステム識別子に対応する英語 `lower_snake_case` 名称。
43
+ - **キー項目(`key_fields`)**: エンティティを一意に識別する業務上のキー項目のリスト。
44
+ - **用語集参照キー(`glossary_term_id`)**: 用語集(glossary)に登録された正式な用語 ID(`tm-...`)。
45
+ - **関連用語(`related_terms`)**: 関連する用語集の用語 ID リスト。
32
46
 
33
47
  ## 3. ファイル命名・ID規則
34
48
 
35
49
  ### 3.1. ID規約
36
50
 
37
- - `id` は正規表現 `^bdd-[a-z0-9-]+$` に合致する一意IDを用いる。
38
- - `type` は `data` 固定とする。
39
- - 置き換えがある場合は `supersedes` に旧IDを列挙する。
51
+ - `id` は `bdd.schema.yaml` の制約に合致する一意 ID を用いる。
52
+ - プロジェクト成果物: `<project-id>:bdd-<name>`(例: `prj-0001:bdd-project-config`)
53
+ - SpecDojo 同梱成果物: `specdojo:bdd-<name>`(例: `specdojo:bdd-sample`)
54
+ - 単体 ID: `bdd-<name>`
55
+ - 成果物メタデータの `type` は `data` 固定とする。
56
+ - **変更管理手順**:
57
+ - 置き換えによる大幅な改訂がある場合は `supersedes` に旧 ID を列挙し、旧 BDD を `status: deprecated` へ移行する(PO 承認)。
58
+ - 用語集(`gl-*.yaml`)や概念クラス図(CCD)が改訂された場合は、保守担当(BA / ARC)が関連する `bdd-*.yaml` の `logical_name`, `glossary_term_id`, `related_terms` を同期更新する。
59
+ - `schema_ref` / `type_ref` の参照元が改訂された場合、ARC / DEV が参照先の移動、フィールドの追加・改名・廃止、キー変更、enum 値の追加・改名・廃止を差分から抽出する。BA / ARC は該当する BDD の参照、`physical_name`、`key_fields`、許容値と業務注釈(論理名・説明・ラベル・用語参照)を照合する。
60
+ - 参照元との対応が未解決の項目は、旧新の対応・影響・確認担当を変更記録に残す。業務注釈の意味を確認し、「成果物の検証手順」を完了するまで更新を受け入れない。値の機械的な置換だけで同期完了としない。
61
+ - **フィールドの非推奨・廃止とアップストリーム削除時の運用パス**:
62
+ - 自発的なフィールドの非推奨・廃止時は、スタンドアロン定義では直接削除せず `description` に非推奨理由および代替フィールドを明記して移行期間を設ける。
63
+ - アップストリーム(正本スキーマまたは TypeScript 型)側ですでにフィールドが削除された場合、アクティブな `fields` に残すと参照元実在項目の手動照合条件と競合する。そのため、ARC / DEV は差分抽出時にアップストリーム削除を検知し、BA とともに次のいずれかの運用パスを実施する:
64
+ 1. **レガシーアノテーションの退避**: アクティブな `fields` リストから削除済みフィールドを外し、エンティティの `description` やレガシー注釈ノートへ非推奨理由・代替フィールド・削除時期・旧アノテーションを移動して記録を保持する。
65
+ 2. **互換ソースバージョンへの紐付け**: 移行期間中にアクティブなフィールド定義・注釈を維持する必要がある場合は、`schema_ref` / `type_ref` の参照先を最新版から当該フィールド削除前の互換バージョン(Git タグ、特定コミット、または安定版スキーマパス)へ明示的に固定(ピン留め)する。移行期間終了時に最新版へ切り替え、レガシーアノテーションを退避する。
66
+ - これにより、移行期間中の業務情報保持と、手動照合における最新正本との厳格な検証可能性(欠落・余分な注釈の排除)を両立する。変更タスクは PM が PJR 項目として管理する。
40
67
 
41
68
  ### 3.2. ファイル命名規約
42
69
 
43
- - ファイルは YAML 形式(`.yaml`)で管理する。
44
-
45
- - ファイル名は、idと同じ名称 `bdd-<term>.yaml` を推奨。日本語の場合は、`業務データ辞書-<用語>.yaml` のように、一貫性を持たせて命名する。
70
+ - **配置ディレクトリ**: プロジェクト内の業務データ辞書は、成果物カタログの `base_path`(通常は `docs/ja/product/010-business-specs/020-data-model/`)直下に配置する。
71
+ - **ファイル形式**: YAML 形式(`.yaml`)で管理する。
72
+ - **ファイル名**: `bdd-<term>.yaml`(英小文字 kebab-case)とする(例: `bdd-project-config.yaml`, `bdd-payment.yaml`)。
46
73
 
47
74
  ## 4. 推奨 Frontmatter 項目
48
75
 
49
- Frontmatter と同等の以下の項目をYAMLドキュメントの先頭に必ず定義してください。
76
+ 独立 YAML のため、メタデータをルートに置き、Markdown 用の `specdojo:` ラッパーや `---` で囲まない。共通の意味はドキュメントメタ情報標準、許可キーと型の詳細は `bdd.schema.yaml` に従う。
77
+
78
+ | 項目 | 説明 | 必須 |
79
+ | ------------ | ---------------------------------------- | ---- |
80
+ | `id` | データ辞書ID(`bdd-...`) | ○ |
81
+ | `type` | 成果物種別(`data` 固定) | ○ |
82
+ | `title` | 対象業務・管理単位が分かる表示名 | ○ |
83
+ | `status` | 状態(`draft` / `ready` / `deprecated`) | ○ |
84
+ | `rulebook` | 準拠ルール(`specdojo:bdd-rulebook`) | ○ |
85
+ | `supersedes` | 置き換え関係(旧IDの配列) | 任意 |
86
+
87
+ ## 5. 本文要件
88
+
89
+ - ファイル先頭のコメントとして `# yaml-language-server: $schema=<相対パス>` を必須とする。パスは出力 YAML ファイルのディレクトリを基準に解決し、BDD 検証用の `docs/specdojo/schemas/v1/bdd.schema.yaml` を指すこと。`schema_ref` が指す業務エンティティのスキーマとは用途が異なる。
90
+ - 例えば `docs/ja/product/010-business-specs/020-data-model/bdd-payment.yaml` では、`# yaml-language-server: $schema=../../../../specdojo/schemas/v1/bdd.schema.yaml` とする。別の配置へこの相対パスをそのまま転記しない。
91
+ - ルートの必須キー `entities` に一つ以上のエンティティを置く。エンティティの管理境界と、注釈を付けるフィールドの選定理由が説明から判断できること。
92
+
93
+ ### 5.1. entities の構成
94
+
95
+ 各エンティティには以下のサブ項目を定義する。
96
+
97
+ | サブ項目 | 説明 | 必須 |
98
+ | ------------------ | ---------------------------------------------------------------------- | -------- |
99
+ | `logical_name` | 業務上の論理名(日本語単数形) | ○ |
100
+ | `physical_name` | DB互換の物理名(`lower_snake_case`) | ○ |
101
+ | `description` | 業務データエンティティの説明・役割 | 任意 |
102
+ | `schema_ref` | 正本スキーマへの参照パス(JSON Schema / YAML Schema 等) | 任意 |
103
+ | `type_ref` | 正本型定義への参照パス(TypeScript 等、例: `src/types/xxx.ts#Type`) | 任意 |
104
+ | `glossary_term_id` | 用語集の用語ID(`tm-...`) | 任意 |
105
+ | `related_terms` | 関連用語IDのリスト | 任意 |
106
+ | `key_fields` | キー項目(`physical_name` のリスト) | ○ |
107
+ | `fields` | 業務データフィールドの一覧(スタンドアロン定義では必須、参照時は任意) | 条件付き |
108
+
109
+ ※ `schema_ref` と `type_ref` は同時に指定できない。どちらも指定しない場合(スタンドアロン定義)は `fields` の定義が必須となる。
110
+
111
+ ### 5.2. fields の構成
112
+
113
+ 各フィールドには以下のサブ項目を定義する。
114
+
115
+ | サブ項目 | 説明 | 必須 |
116
+ | ------------------------- | ------------------------------------------------------------------------------------------------------------- | -------- |
117
+ | `logical_name` | 業務上の論理名(日本語単数形) | ○ |
118
+ | `physical_name` | DB互換の物理名(`lower_snake_case`) | ○ |
119
+ | `glossary_term_id` | 用語集の用語ID(`tm-...`) | 任意 |
120
+ | `type` | データ型(`integer` / `string` / `boolean` / `date` / `datetime` / `enum` / `money`。スタンドアロン時は必須) | 条件付き |
121
+ | `description` | フィールドの業務的説明・役割 | 任意 |
122
+ | `unit` | 単位(該当時、例: 円、個、kg) | 任意 |
123
+ | `constraints` | フィールドの制約条件(スタンドアロン定義時) | 任意 |
124
+ | `example` | フィールドの例値 | 任意 |
125
+ | `allowed_values` | 許容値リスト(簡易列挙。`type: enum` または状態定義時) | 条件付き |
126
+ | `allowed_values_detailed` | 許容値と業務ラベルのリスト(詳細列挙。`type: enum` または状態定義時) | 条件付き |
127
+
128
+ ※ `type: enum` を指定する場合、またはスキーマ・型参照エンティティで業務状態の許容値を定義する場合、`allowed_values` または `allowed_values_detailed` のいずれか一方を必須とする。
129
+ ※ `schema_ref` または `type_ref` を指定したエンティティでは、`type` や `constraints` は参照先で定義されているため省略し、業務上の意味(`description` や `allowed_values_detailed`)のみを記述する。
130
+
131
+ ### 5.3. constraints の構成
132
+
133
+ スタンドアロン定義で制約条件を明記する場合、以下のサブ項目を用いる。
134
+
135
+ | サブ項目 | 説明 | 必須 |
136
+ | ---------- | -------------------------------- | ---- |
137
+ | `required` | 必須入力かどうか(true / false) | 任意 |
138
+ | `unique` | 一意性制約(true / false) | 任意 |
139
+ | `min` | 最小値 | 任意 |
140
+ | `max` | 最大値 | 任意 |
141
+ | `pattern` | 正規表現パターン | 任意 |
50
142
 
51
- | 項目 | 説明 | 必須 |
52
- | ---------- | ---------------------------------------- | ---- |
53
- | id | データ辞書ID(`bdd-...`) | ○ |
54
- | type | `data` 固定 | ○ |
55
- | title | ドキュメント名。表示ページの見出しになる | ○ |
56
- | status | `draft` / `ready` / `deprecated` | ○ |
57
- | rulebook | `specdojo:bdd-rulebook` 固定 | ○ |
58
- | supersedes | 置き換え関係(古仕様→新仕様) | 任意 |
143
+ ## 6. 記述ガイド
59
144
 
60
- ## 5. 本文構成(標準テンプレ)
145
+ ### 6.1. 記述の基本方針
61
146
 
62
- | キー | 説明 | 必須 |
63
- | ---- | ---- | ---- |
147
+ メタ情報・エンティティ・フィールドは、次の基準で書き分ける。共通事項は「位置づけと用語定義」で示した上位文書を正本とする。
64
148
 
65
- | entities | 業務データエンティティの一覧 | ○ |
149
+ | 対象 | 判断の基準 | 良い例 | 悪い例 |
150
+ | -------------------------- | ------------------------------------------ | -------------------------------------------------------------- | -------------------------------------------------- |
151
+ | メタ情報 | ID と表示名から対象を識別できる | `bdd-register-entry`、業務データ辞書(登録項目個票) | タイトルが「データ定義」のみで対象が不明 |
152
+ | エンティティの説明 | 管理単位・範囲・他の正本との境界が分かる | 「登録簿で個別に追跡する作業・課題。状態遷移は状態定義を参照」 | 「登録項目の情報」のみ、または状態遷移表を複写 |
153
+ | フィールドの説明 | 業務判断に使う意味と区別すべき概念が分かる | 「文書成熟度。対応の進捗を表す処理状態とは別の判断軸」 | 「状態」や「文字列」のみ |
154
+ | スタンドアロンの単位・制約 | 業務上の根拠を持つ条件だけを定義する | 数量の単位を「個」とし、受注可能数の下限を業務ルールから定める | 根拠のない上限を設定する、参照元の制約を重ねて書く |
66
155
 
67
- ### 5.1. entities の標準構成
156
+ ### 6.2. スキーマ・実装参照と選定基準
68
157
 
69
- | サブ項目 | 説明 | 必須 |
70
- | ------------- | ---------------------------------- | ---- |
71
- | logical_name | 業務上の論理名(日本語単数形) | ○ |
72
- | physical_name | DB互換の物理名(lower_snake_case) | ○ |
158
+ エンティティの定義形態は、対象データの仕様管理状況に応じて次の3通りから選定する。
73
159
 
74
- | description | 業務データの説明 | 任意 |
160
+ #### 6.2.1. schema があるエンティティ(スキーマ参照: `schema_ref`)
75
161
 
76
- | glossary_term_id | 用語集の用語ID | 任意 |
77
- | related_terms | 関連用語IDリスト | 任意 |
78
- | key_fields | キー項目(`physical_name` のリスト) | ○ |
162
+ - **選定基準**: 対象エンティティの JSON Schema / YAML Schema / OpenAPI 仕様が既に存在し、物理構造・制約の正本として管理されている場合に選択する。
163
+ - **記述規則**:
164
+ - `schema_ref` に正本スキーマのファイルパス(例: `schemas/payment.schema.yaml`)またはポインタ(例: `schemas/order.schema.yaml#/$defs/Payment`)を明記する。
165
+ - `fields` には、スキーマから読み取れない業務上の意味(項目の業務的定義、enum の値が表す業務上の状態遷移や業務ルール上の分岐など)だけを書く。
166
+ - データ型(`type`)、必須(`required`)、最小/最大(`min` / `max`)、パターン(`pattern`)など、スキーマに定義済みの制約は絶対に繰り返さない。
167
+ - **良い例**: `schema_ref` で支払いの正本を示し、状態項目の注釈で「入金確認が済み、出荷判断に使える状態」と説明する。
168
+ - **悪い例**: 正本に定義済みの `type: string` や `constraints.required: true` を転記し、説明を「文字列」にとどめる。
79
169
 
80
- | fields | 業務データフィールドの一覧 | ○ |
170
+ #### 6.2.2. schema のないエンティティの選定基準(スタンドアロン定義 vs TypeScript 型参照)
81
171
 
82
- ### 5.2. fields の標準構成
172
+ スキーマが存在しないエンティティは、開発フェーズや正本の所在に応じて次のいずれかを選択する。
83
173
 
84
- | サブ項目 | 説明 | 必須 |
85
- | ------------- | ---------------------------------- | ---- |
86
- | logical_name | 業務上の論理名(日本語単数形) | ○ |
87
- | physical_name | DB互換の物理名(lower_snake_case) | ○ |
174
+ | 方式 | 選定基準 | 記述規則 |
175
+ | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
176
+ | **スタンドアロン定義** | 実装(コードやDB)が未着手の企画・要求分析初期フェーズ、または特定の実装言語に依存しない純粋なドメイン概念モデルを独立して定義したい場合に選択する | `fields` に `type`、`constraints`、`example` などの物理・論理仕様を直接定義する。 |
177
+ | **TypeScript 型参照(`type_ref`)** | すでに TypeScript で `interface` や `type` が正本として実装・運用されており、JSON Schema がない内部モデルや設定値の業務仕様を整理する場合に選択する | `type_ref` に型定義パス(例: `src/types/xxx.ts#Type`)を明記し、`fields` にはコードから読めない業務的意味のみを記述する。 |
88
178
 
89
- | glossary_term_id | 用語集の用語ID | 任意 |
90
- | type | データ型(integer / string / boolean / date / datetime / enum / money) | ○ |
91
- | description | フィールドの説明 | 任意 |
92
- | unit | 単位(該当時) | 任意 |
93
- | constraints | フィールドの制約条件 | 任意 |
94
- | example | フィールドの例値 | 任意 |
179
+ - **良い例**: 実装前の商品数量をスタンドアロンで `type: integer`、`unit: 個` と定義する。型が正本になった内部取引は `type_ref` を示し、業務上の区分だけを注釈する。
180
+ - **悪い例**: 実在する正本を調べずにスタンドアロンで同じ型を定義する、または型のない項目へ推測で `type_ref` を付ける。
95
181
 
96
- ### 5.3. constraints の標準構成
182
+ ### 6.3. 命名と参照の指針
97
183
 
98
- | サブ項目 | 説明 | 必須 |
99
- | -------- | -------------------------------- | ---- |
100
- | required | 必須入力かどうか(true / false) | 任意 |
101
- | unique | 一意性制約(true / false) | 任意 |
102
- | min | 最小値 | 任意 |
103
- | max | 最大値 | 任意 |
104
- | pattern | 正規表現パターン | 任意 |
184
+ - 論理名は日本語単数形とする(例: `商品`, `支払い`)。
185
+ - 物理名(`physical_name`)は entity / field とも `lower_snake_case` を用いる(例: `product_code`, `credit_balance`, `payment_status`)。
186
+ - 参照先の lowerCamelCase 名と対応させる場合は相互変換を確認する。参照先の定義がネストされている場合は、対象位置をポインタまたは説明で特定し、同名の別項目と区別する。
187
+ - `key_fields` は `physical_name` を指定する。
188
+ - `glossary_term_id` は用語集で定義された ID(`tm-...`)と厳密に一致させる。
189
+ - `schema_ref` / `type_ref` はリポジトリルートから辿れるパスと対象定義を示す。キー一覧は参照先で確認し、`fields` は業務注釈が必要な項目に絞ってよい。
190
+ - **良い例**: `key_fields: [product_code]` が実際の識別項目に対応し、`glossary_term_id: tm-product-code` が対象用語集に存在する。
191
+ - **悪い例**: `key_fields` に論理名を指定する、表示用の導出値を保存キーとして扱う、用語 ID の存在を名前から推測する。
105
192
 
106
- ## 6. 記述ガイド
193
+ ### 6.4. enum および業務ステータスの記述方法
107
194
 
108
- ### 6.1. 記述の基本方針
195
+ - enum フィールドや状態遷移を持つ項目では、許容値を必ず明示する。
196
+ - 記述方式は用途に応じて選択する:
197
+ - **簡易列挙(`allowed_values`)**: 値の名称自体で意味が自明な場合(例: `allowed_values: [PENDING, PAID, CANCELED]`)。
198
+ - **詳細列挙(`allowed_values_detailed`)**: 各値が表す業務上の状態や画面表示名を明示する場合(`value` と `label` を指定)。スキーマ参照エンティティで状態の業務的意味を定義する際は、原則として詳細列挙を用いる。
199
+ - **判断基準**: 値の詳細な構文や遷移条件は正本へ譲り、辞書では値と業務上の意味の対応を確認できる粒度にする。参照元の enum 値と過不足なく対応させ、ラベルだけを値として置き換えない。
200
+ - **良い例**: `value: PAID` に `label: 入金確認済み` を対応させる。状態遷移や承認条件は、その正本を説明から参照する。
201
+ - **悪い例**: 同じフィールドに `allowed_values` と `allowed_values_detailed` を併記する、参照元にない値を追加する、状態遷移の仕様を辞書へ複写する。
202
+
203
+ ### 6.5. 成果物の検証手順
204
+
205
+ 作成・改訂した業務データ辞書 YAML は、機械検証と手動照合の両方で判定する。変更記録には対象ファイル・参照した正本・実行コマンドと終了結果・手動照合の結果を残す。
206
+
207
+ #### 6.5.1. 個別の構造・modeline 検証
208
+
209
+ ```bash
210
+ npm run validate:schema:file -- --schema docs/specdojo/schemas/v1/bdd.schema.yaml --data <対象YAMLファイルパス>
211
+ node packages/docs-lint/bin/specdojo-docs-lint.js yaml-schema --modeline <対象YAMLファイルパス>
212
+ ```
213
+
214
+ - **期待結果**: 両方が対象ファイルを `valid` と表示して終了コード 0 となること。明示的な `--schema` 指定の合格だけでは、先頭コメントの存在や相対パスの正しさを確認したことにならない。
215
+
216
+ #### 6.5.2. 全体検証と整形
217
+
218
+ ```bash
219
+ npm run validate:schema
220
+ npx prettier --check <対象YAMLファイルパス>
221
+ ```
222
+
223
+ - **期待結果**: 全体検証が終了コード 0、対象 YAML の整形差分がゼロであること。失敗時は報告された対象・キー・参照先を確認して修正し、該当検査を再実行する。
224
+ - **検証の限界**: `validate:schema:glossary` は用語集内の用語間参照を検査し、BDD の `glossary_term_id` / `related_terms` の参照解決は検査しない。`bdd.schema.yaml` はスタンドアロンの各フィールドの `type` 必須、列挙方式の排他性、参照元との意味・値・キーの一致を保証しない。これらは次の手動照合で判定する。
225
+
226
+ #### 6.5.3. 業務要件と参照整合の手動照合
227
+
228
+ BA / ARC は以下の合格条件を一つずつ確認し、DEV は参照元との対応、QE は証跡を確認する。該当しない行は対象形態と理由を記録する。
229
+
230
+ | 確認対象 | 合格条件 | 残す証跡 |
231
+ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
232
+ | スタンドアロン定義 | 全フィールドに `type` があり、単位・制約・例値が業務上の意味と矛盾しない | エンティティ・フィールドと確認結果 |
233
+ | enum・業務状態 | 対象項目に空でない列挙を一方式だけ持つ。詳細列挙では `value` が重複せず、各ラベルで業務上の意味を識別できる | フィールド・方式・値と意味の確認結果 |
234
+ | 用語集・CCD | エンティティとフィールドの全 `glossary_term_id`、全 `related_terms` が対象用語集の用語 ID に存在し、論理名・意味が用語集と CCD に整合する | 対象用語集・CCD の ID と照合箇所。該当文書がない場合は理由 |
235
+ | フィールドとキー | スタンドアロンでは `key_fields` の全要素が `fields` に存在する。参照型では参照先のファイルと対象定義が存在し、注釈する全フィールドとキーが正本の実在項目に対応する(アップストリーム削除済みのフィールドは、レガシーアノテーション退避または互換バージョンへの固定が行われていること)。いずれも単独・複合キーとしての識別意味が一致する | 対象定義・キーとフィールドの対応、および退避・バージョン固定の証跡 |
236
+ | 参照元の許容値 | 参照元の enum 値と辞書の列挙に不足・余分がなく、業務ラベルが各値の意味に一致する | フィールド・参照元の定義位置・値ごとの対応 |
237
+ | 二重管理の防止 | 参照型の `fields` に `type` / `constraints` を再掲せず、業務上の判断に必要な注釈だけを持つ。状態遷移・承認条件は正本へ参照する | 注釈の選定と重複の有無 |
238
+
239
+ - **良い判定例**: 個別検証と modeline 検証の成功に加え、用語 ID・キー・enum 値を正本の箇所と対応付けて合格を記録する。
240
+ - **悪い判定例**: `validate:schema` の終了コード 0 だけで、辞書の参照と業務注釈も整合していると判定する。
241
+
242
+ ### 6.6. rulebook 改訂候補の enum 網羅確認
109
243
 
110
- - 業務視点の論理名・説明を重視し、実装要素は必要最小限に留める。
111
- - データ項目の意味・制約・例値・関連情報を簡潔かつ明確に記述する。
112
- - エンティティ・項目の論理名と説明は、概念クラス図(CCD)と用語集(glossary)に整合させる。
244
+ `npm run validate:schema:rulebook-enums` は `ready` の YAML / JSON rulebook だけを対象とする。`draft` の本書に対しては、コマンド全体の成功を網羅確認の証跡にしない。
113
245
 
114
- ### 6.2. 命名と参照の指針
246
+ 1. `draft` を維持したまま、`docs/specdojo/schemas/v1/bdd.schema.yaml` 内のすべての文字列 enum を定義位置ごとに抽出する。入れ子の定義も確認し、scaffold 専用のプレースホルダは除く。
247
+ 2. 各値が本書の本文に独立した値として明記されているか照合する。Frontmatter と finding コメントは数えない。値の追加・変更時には対応する用途の説明も確認する。
248
+ 3. 次の列で対象別の照合記録を残す。全値の対応が埋まり、欠落がゼロであることを確定前の合格条件とする。
115
249
 
116
- - 論理名は日本語単数形で記載する。
117
- - 物理名(`physical_name`)は entity / field とも lower_snake_case を用いる(例: `product_code`, `credit_balance`, `payment_status`)。
118
- - アプリケーション(TypeScript等)で利用する場合は、`physical_name` を lowerCamelCase に変換して扱う。
119
- - `key_fields` は `physical_name` を参照する。
120
- - `glossary_term_id` は用語集で定義されたIDと一致させる。
250
+ | 証跡の列 | 記録する内容 |
251
+ | ----------------- | ------------------------------------------------------------------- |
252
+ | 対象と版 | 本 rulebook と BDD 検証スキーマのパス、照合時の版または内容ハッシュ |
253
+ | enum 定義位置・値 | スキーマ内の定義位置と各文字列値 |
254
+ | 本文の記載位置 | その値を記載した見出し名と行、または未記載 |
255
+ | 判定・確認者 | 値ごとの合否、欠落数、確認者 |
121
256
 
122
- ### 6.3. enum の記述方法
257
+ 4. 人間による最終承認にはこの対象別証跡を添える。昇格後は通常コマンドの出力にも本書のパスを含む `enum coverage valid` があることを確認する。
123
258
 
124
- - `type: enum` のフィールドは許容値を必ず明示する。
125
- - 記述方式は次のいずれかを採用する。
126
- - 簡易列挙: `allowed_values: [PENDING, PAID, CANCELED]`
127
- - 詳細列挙: `allowed_values_detailed:` に `value` と `label` を持つ配列を記述する。
259
+ - **良い例**: `draft` の改訂候補とスキーマを直接照合し、各値の本文位置と欠落ゼロを記録する。
260
+ - **悪い例**: 対象パスが出力されていない通常コマンドの成功を根拠にする、または確認のために本書を `ready` へ書き換える。
128
261
 
129
262
  ## 7. 禁止事項
130
263
 
131
- - 技術的属性(`created_at`, `updated_at`, `deleted_at` など)を原則含めない。
132
- - 実装都合のカラムや API 用の構造体をそのまま記載しない。
133
- - 用語集や CCD と不整合な用語・IDを使わない。
134
- - 物理名と論理名で英語・日本語を無秩序に混在させない。
135
- - 意味が曖昧な説明や略語のみの記載をしない。
264
+ - **技術的属性の無断追加の禁止**: 業務要件として監査証跡や有効期限管理・世代管理が明示的に要求され、プロダクトオーナー(PO)またはアーキテクト(ARC)が認めた場合を除き、技術的属性(`created_at`, `updated_at`, `deleted_at` 等)を含めない。例外として含める場合は、業務上の必要性(法的要件・監査要件等)をフィールドの説明(`description`)に明記する。
265
+ - **スキーマ・実装定義の二重管理・重複記述の禁止**: `schema_ref` や `type_ref` を指定したエンティティにおいて、正本側に既に定義されているデータ型(`type`)や制約条件(`constraints`)を `fields` 内に再掲・重複記述しない。
266
+ - **言語混在・不規則な命名の禁止**: 論理名(`logical_name`)に英数字のみの識別子を記述したり、物理名(`physical_name`)に日本語や `lower_snake_case` 以外の記法(UpperCamelCase、kebab-case、空白混在等)を使用したりしない。
267
+ - **用語集・CCD との不整合の禁止**: 用語集や CCD で定義された用語・ID と異なる名称や略称を使用しない。
268
+ - **曖昧な説明・略語のみの記述の禁止**: 意味が不明瞭な説明や、業務的な文脈を欠いた略語のみの記述をしない。