specdojo 0.4.6 → 0.5.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 (310) hide show
  1. package/.github/agents/specdojo-orchestrator.md +14 -9
  2. package/CHANGELOG.md +62 -0
  3. package/dist/catalog/document-target.js +75 -0
  4. package/dist/commands/agent.js +2 -80
  5. package/dist/commands/init.js +3 -0
  6. package/dist/commands/night-orchestrator.js +33 -4
  7. package/dist/dashboard/dashboard.js +5 -6
  8. package/dist/dashboard/timeline-build.js +5 -1
  9. package/dist/dashboard/timeline.js +6 -3
  10. package/dist/docs/yaml-pages.js +17 -17
  11. package/dist/exec/agent-config.js +28 -16
  12. package/dist/exec/agent-plan.js +108 -0
  13. package/dist/exec/commands.js +3 -3
  14. package/dist/exec/core.js +2 -0
  15. package/dist/exec/grade-checkpoint.js +12 -0
  16. package/dist/exec/pipeline-state.js +5 -2
  17. package/dist/exec/plans-core.js +7 -67
  18. package/dist/exec/plans-generation.js +28 -7
  19. package/dist/exec/plans-grade-findings.js +16 -0
  20. package/dist/exec/plans-planning.js +43 -0
  21. package/dist/exec/plans-storage.js +5 -2
  22. package/dist/exec/project.js +4 -1
  23. package/dist/exec/register.js +82 -6
  24. package/dist/exec/repo-integration-sync.js +9 -0
  25. package/dist/exec/repo-integration.js +17 -2
  26. package/dist/exec/repo-trace.js +17 -4
  27. package/dist/exec/results.js +2 -0
  28. package/dist/exec/run/lifecycle-commands.js +2 -0
  29. package/dist/exec/run/register-core.js +11 -0
  30. package/dist/exec/run/register-mode.js +19 -1
  31. package/dist/exec/run/register-resume.js +23 -0
  32. package/dist/exec/run/register-state.js +4 -1
  33. package/dist/exec/run/register-worktree.js +28 -1
  34. package/dist/exec/run/schedule-prepare.js +7 -1
  35. package/dist/exec/strategy.js +2 -0
  36. package/dist/exec/task-repos.js +18 -4
  37. package/dist/exec/worktree-command.js +8 -1
  38. package/dist/exec/worktree-ops-commit.js +7 -1
  39. package/dist/exec/worktree-ops-merge.js +40 -1
  40. package/dist/grade/apply.js +13 -7
  41. package/dist/grade/command-inspect.js +2 -1
  42. package/dist/grade/command-run.js +39 -0
  43. package/dist/grade/grade.js +3 -1
  44. package/dist/grade/markdown.js +11 -6
  45. package/dist/grade/pipeline-state.js +8 -6
  46. package/dist/grade/plan.js +14 -10
  47. package/dist/grade/run.js +307 -0
  48. package/dist/grade/target-discovery.js +1 -1
  49. package/dist/grade/targets.js +44 -22
  50. package/dist/register/approach.js +35 -0
  51. package/dist/register/catalog-status.js +49 -0
  52. package/dist/register/core.js +5 -0
  53. package/dist/register/create-commands.js +83 -5
  54. package/dist/register/deliverable-target.js +215 -0
  55. package/dist/register/dependency.js +123 -0
  56. package/dist/register/derivation.js +2 -2
  57. package/dist/register/epic.js +42 -0
  58. package/dist/register/event-merge.js +5 -2
  59. package/dist/register/events.js +8 -0
  60. package/dist/register/external-project.js +4 -0
  61. package/dist/register/item.js +18 -0
  62. package/dist/register/maintenance-commands.js +7 -1
  63. package/dist/register/planning.js +37 -0
  64. package/dist/register/register.js +5 -1
  65. package/dist/register/renumber.js +12 -4
  66. package/dist/register/views.js +55 -4
  67. package/dist/review/grade.js +19 -17
  68. package/dist/schedule/schedule.js +3 -1
  69. package/dist/schedule/strategy-generate-scope.js +5 -1
  70. package/dist/schedule/strategy-generate.js +1 -0
  71. package/dist/schedule/strategy-profiles.js +1 -1
  72. package/dist/shared/agent-plan.js +1 -0
  73. package/dist/shared/agent-types.js +3 -0
  74. package/dist/shared/grade-result.js +23 -5
  75. package/dist/shared/markdownlint-config.js +38 -0
  76. package/dist/shared/markdownlint-scaffold.js +2 -9
  77. package/dist/shared/provider-scaffold.js +5 -3
  78. package/dist/shared/specdojo-config.js +10 -3
  79. package/dist/shared/specdojo-gitignore.js +4 -0
  80. package/dist/specdojo.js +5 -1
  81. package/docs/ja/specdojo/exec-templates/xep-catalog-planning-template.md +24 -0
  82. package/docs/ja/specdojo/exec-templates/xep-strategy-planning-template.md +24 -0
  83. package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +2 -2
  84. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +2 -2
  85. package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +2 -2
  86. package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +2 -2
  87. package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +2 -2
  88. package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +2 -2
  89. package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +2 -2
  90. package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +2 -2
  91. package/docs/ja/specdojo/exec-templates/xrp-template.md +2 -2
  92. package/docs/ja/specdojo/guides/docs-editing-guide.md +14 -1
  93. package/docs/ja/specdojo/guides/docs-structure-guide.md +10 -8
  94. package/docs/ja/specdojo/guides/exec-config-guide.md +44 -12
  95. package/docs/ja/specdojo/guides/exec-operation-guide.md +20 -15
  96. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +19 -1
  97. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +3 -1
  98. package/docs/ja/specdojo/guides/practice-system-composition-guide.md +2 -0
  99. package/docs/ja/specdojo/guides/quick-start-guide.md +59 -16
  100. package/docs/ja/specdojo/guides/register-operation-guide.md +44 -15
  101. package/docs/ja/specdojo/guides/remote-host-development-guide.md +15 -1
  102. package/docs/ja/specdojo/guides/review-guide.md +2 -2
  103. package/docs/ja/specdojo/guides/ryu-guide.md +12 -0
  104. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +16 -16
  105. package/docs/ja/specdojo/guides/timeline-design-guide.md +37 -33
  106. package/docs/ja/specdojo/recipes/tsd-recipe.md +198 -0
  107. package/docs/ja/specdojo/references/command-reference.md +92 -29
  108. package/docs/ja/specdojo/references/specdojo-config-reference.md +49 -16
  109. package/docs/ja/specdojo/rulebooks/atc-index-rulebook.md +1 -0
  110. package/docs/ja/specdojo/rulebooks/atc-rulebook.md +1 -0
  111. package/docs/ja/specdojo/rulebooks/bac-rulebook.md +5 -4
  112. package/docs/ja/specdojo/rulebooks/bdd-rulebook.md +3 -2
  113. package/docs/ja/specdojo/rulebooks/bds-rulebook.md +4 -3
  114. package/docs/ja/specdojo/rulebooks/bes-index-rulebook.md +8 -7
  115. package/docs/ja/specdojo/rulebooks/bes-rulebook.md +4 -3
  116. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +1 -0
  117. package/docs/ja/specdojo/rulebooks/br-rulebook.md +1 -0
  118. package/docs/ja/specdojo/rulebooks/ccd-mermaid-rulebook.md +1 -0
  119. package/docs/ja/specdojo/rulebooks/cdfd-mermaid-rulebook.md +1 -0
  120. package/docs/ja/specdojo/rulebooks/cdfd-overview-rulebook.md +1 -0
  121. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +1 -0
  122. package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +1 -0
  123. package/docs/ja/specdojo/rulebooks/cdsd-rulebook.md +3 -2
  124. package/docs/ja/specdojo/rulebooks/cld-rulebook.md +2 -1
  125. package/docs/ja/specdojo/rulebooks/cnd-mermaid-rulebook.md +1 -0
  126. package/docs/ja/specdojo/rulebooks/cnd-rulebook.md +1 -0
  127. package/docs/ja/specdojo/rulebooks/cop-index-rulebook.md +2 -1
  128. package/docs/ja/specdojo/rulebooks/cop-rulebook.md +3 -2
  129. package/docs/ja/specdojo/rulebooks/cpd-mermaid-rulebook.md +1 -0
  130. package/docs/ja/specdojo/rulebooks/cpd-rulebook.md +1 -0
  131. package/docs/ja/specdojo/rulebooks/cstd-rulebook.md +1 -0
  132. package/docs/ja/specdojo/rulebooks/cxd-mermaid-rulebook.md +1 -0
  133. package/docs/ja/specdojo/rulebooks/cxd-rulebook.md +1 -0
  134. package/docs/ja/specdojo/rulebooks/dct-index-rulebook.md +1 -0
  135. package/docs/ja/specdojo/rulebooks/dct-rulebook.md +1 -0
  136. package/docs/ja/specdojo/rulebooks/dec-rulebook.md +1 -0
  137. package/docs/ja/specdojo/rulebooks/dmd-index-rulebook.md +2 -1
  138. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +2 -1
  139. package/docs/ja/specdojo/rulebooks/etc-index-rulebook.md +1 -0
  140. package/docs/ja/specdojo/rulebooks/etc-rulebook.md +1 -0
  141. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +9 -6
  142. package/docs/ja/specdojo/rulebooks/ifd-mermaid-rulebook.md +1 -0
  143. package/docs/ja/specdojo/rulebooks/ifx-api-rulebook.md +3 -1
  144. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +2 -1
  145. package/docs/ja/specdojo/rulebooks/ifx-file-rulebook.md +2 -1
  146. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +2 -0
  147. package/docs/ja/specdojo/rulebooks/ifx-msg-rulebook.md +4 -2
  148. package/docs/ja/specdojo/rulebooks/imp-business-rulebook.md +1 -0
  149. package/docs/ja/specdojo/rulebooks/imp-data-rulebook.md +1 -0
  150. package/docs/ja/specdojo/rulebooks/imp-interface-rulebook.md +1 -0
  151. package/docs/ja/specdojo/rulebooks/imp-operations-rulebook.md +1 -0
  152. package/docs/ja/specdojo/rulebooks/imp-test-rulebook.md +1 -0
  153. package/docs/ja/specdojo/rulebooks/itc-index-rulebook.md +1 -0
  154. package/docs/ja/specdojo/rulebooks/itc-rulebook.md +1 -0
  155. package/docs/ja/specdojo/rulebooks/mip-index-rulebook.md +2 -1
  156. package/docs/ja/specdojo/rulebooks/mm-rulebook.md +1 -0
  157. package/docs/ja/specdojo/rulebooks/mtp-rulebook.md +4 -3
  158. package/docs/ja/specdojo/rulebooks/nfr-availability-rulebook.md +9 -8
  159. package/docs/ja/specdojo/rulebooks/nfr-index-rulebook.md +10 -9
  160. package/docs/ja/specdojo/rulebooks/nfr-integrity-rulebook.md +9 -8
  161. package/docs/ja/specdojo/rulebooks/nfr-maintainability-rulebook.md +9 -8
  162. package/docs/ja/specdojo/rulebooks/nfr-operations-rulebook.md +9 -8
  163. package/docs/ja/specdojo/rulebooks/nfr-performance-rulebook.md +9 -8
  164. package/docs/ja/specdojo/rulebooks/nfr-reliability-rulebook.md +10 -9
  165. package/docs/ja/specdojo/rulebooks/nfr-security-safety-rulebook.md +9 -8
  166. package/docs/ja/specdojo/rulebooks/nfr-usability-rulebook.md +9 -8
  167. package/docs/ja/specdojo/rulebooks/ntp-rulebook.md +7 -6
  168. package/docs/ja/specdojo/rulebooks/opd-index-rulebook.md +1 -0
  169. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +1 -0
  170. package/docs/ja/specdojo/rulebooks/opr-index-rulebook.md +1 -0
  171. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +1 -0
  172. package/docs/ja/specdojo/rulebooks/otp-index-rulebook.md +2 -1
  173. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +2 -1
  174. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +56 -36
  175. package/docs/ja/specdojo/rulebooks/pm-change-request-log-rulebook.md +1 -0
  176. package/docs/ja/specdojo/rulebooks/pm-communication-plan-rulebook.md +1 -0
  177. package/docs/ja/specdojo/rulebooks/pm-issue-log-rulebook.md +1 -0
  178. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +1 -0
  179. package/docs/ja/specdojo/rulebooks/pm-organization-rulebook.md +1 -0
  180. package/docs/ja/specdojo/rulebooks/pm-plan-rulebook.md +1 -0
  181. package/docs/ja/specdojo/rulebooks/pm-quality-management-plan-rulebook.md +1 -0
  182. package/docs/ja/specdojo/rulebooks/pm-raci-rulebook.md +1 -0
  183. package/docs/ja/specdojo/rulebooks/pm-risk-register-rulebook.md +1 -0
  184. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +1 -0
  185. package/docs/ja/specdojo/rulebooks/pr-rulebook.md +1 -0
  186. package/docs/ja/specdojo/rulebooks/prj-assumptions-constraints-dependencies-rulebook.md +1 -0
  187. package/docs/ja/specdojo/rulebooks/prj-charter-rulebook.md +1 -0
  188. package/docs/ja/specdojo/rulebooks/prj-comparison-of-alternatives-rulebook.md +1 -0
  189. package/docs/ja/specdojo/rulebooks/prj-issues-and-approach-rulebook.md +1 -0
  190. package/docs/ja/specdojo/rulebooks/prj-overview-rulebook.md +1 -0
  191. package/docs/ja/specdojo/rulebooks/prj-scope-rulebook.md +1 -0
  192. package/docs/ja/specdojo/rulebooks/prj-stakeholder-register-rulebook.md +1 -0
  193. package/docs/ja/specdojo/rulebooks/prj-success-criteria-and-acceptance-criteria-rulebook.md +1 -0
  194. package/docs/ja/specdojo/rulebooks/sac-rulebook.md +3 -2
  195. package/docs/ja/specdojo/rulebooks/sch-rulebook.md +1 -0
  196. package/docs/ja/specdojo/rulebooks/sf-index-rulebook.md +7 -6
  197. package/docs/ja/specdojo/rulebooks/sf-rulebook.md +4 -3
  198. package/docs/ja/specdojo/rulebooks/sld-rulebook.md +2 -1
  199. package/docs/ja/specdojo/rulebooks/stc-index-rulebook.md +1 -0
  200. package/docs/ja/specdojo/rulebooks/stc-rulebook.md +1 -0
  201. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +1 -0
  202. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +1 -0
  203. package/docs/ja/specdojo/rulebooks/sysd-critical-flows-rulebook.md +2 -1
  204. package/docs/ja/specdojo/rulebooks/sysd-cross-cutting-policy-rulebook.md +9 -8
  205. package/docs/ja/specdojo/rulebooks/sysd-index-rulebook.md +2 -1
  206. package/docs/ja/specdojo/rulebooks/sysd-rulebook.md +1 -0
  207. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +1 -0
  208. package/docs/ja/specdojo/rulebooks/trc-requirements-to-specs-rulebook.md +1 -0
  209. package/docs/ja/specdojo/rulebooks/trc-requirements-to-tests-rulebook.md +1 -0
  210. package/docs/ja/specdojo/rulebooks/tsd-index-rulebook.md +80 -61
  211. package/docs/ja/specdojo/rulebooks/tsd-rulebook.md +111 -63
  212. package/docs/ja/specdojo/rulebooks/tsp-index-rulebook.md +1 -0
  213. package/docs/ja/specdojo/rulebooks/uis-rulebook.md +3 -2
  214. package/docs/ja/specdojo/rulebooks/utc-index-rulebook.md +1 -0
  215. package/docs/ja/specdojo/rulebooks/utc-rulebook.md +1 -0
  216. package/docs/ja/specdojo/samples/atc-index-sample.md +1 -1
  217. package/docs/ja/specdojo/samples/atc-sample.md +1 -1
  218. package/docs/ja/specdojo/samples/bac-sample.md +1 -1
  219. package/docs/ja/specdojo/samples/bdd-sample.yaml +1 -1
  220. package/docs/ja/specdojo/samples/bds-sample.md +1 -1
  221. package/docs/ja/specdojo/samples/bes-index-sample.md +1 -1
  222. package/docs/ja/specdojo/samples/bes-sample.md +1 -1
  223. package/docs/ja/specdojo/samples/ccd-sample.md +1 -1
  224. package/docs/ja/specdojo/samples/cdfd-sample.md +1 -1
  225. package/docs/ja/specdojo/samples/cdfd-uc-sample.md +1 -1
  226. package/docs/ja/specdojo/samples/cdsd-sample.md +1 -1
  227. package/docs/ja/specdojo/samples/cld-sample.md +1 -1
  228. package/docs/ja/specdojo/samples/cnd-sample.md +1 -1
  229. package/docs/ja/specdojo/samples/cop-index-sample.md +1 -1
  230. package/docs/ja/specdojo/samples/cop-sample.md +1 -1
  231. package/docs/ja/specdojo/samples/cpd-sample.md +1 -1
  232. package/docs/ja/specdojo/samples/cstd-sample.md +1 -1
  233. package/docs/ja/specdojo/samples/cxd-sample.md +1 -1
  234. package/docs/ja/specdojo/samples/dmd-index-sample.md +1 -1
  235. package/docs/ja/specdojo/samples/dmd-sample.md +1 -1
  236. package/docs/ja/specdojo/samples/etc-index-sample.md +1 -1
  237. package/docs/ja/specdojo/samples/etc-sample.md +1 -1
  238. package/docs/ja/specdojo/samples/gl-sample.yaml +2 -0
  239. package/docs/ja/specdojo/samples/ifd-sample.md +1 -1
  240. package/docs/ja/specdojo/samples/ifx-api-sample.yaml +1 -0
  241. package/docs/ja/specdojo/samples/ifx-cmd-sample.yaml +1 -1
  242. package/docs/ja/specdojo/samples/ifx-file-sample.md +1 -1
  243. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +1 -0
  244. package/docs/ja/specdojo/samples/ifx-msg-sample.yaml +2 -1
  245. package/docs/ja/specdojo/samples/itc-index-sample.md +1 -1
  246. package/docs/ja/specdojo/samples/itc-sample.md +1 -1
  247. package/docs/ja/specdojo/samples/mtp-sample.md +1 -1
  248. package/docs/ja/specdojo/samples/nfr-availability-sample.md +1 -1
  249. package/docs/ja/specdojo/samples/nfr-index-sample.md +1 -1
  250. package/docs/ja/specdojo/samples/nfr-integrity-sample.md +1 -1
  251. package/docs/ja/specdojo/samples/nfr-maintainability-sample.md +1 -1
  252. package/docs/ja/specdojo/samples/nfr-operations-sample.md +1 -1
  253. package/docs/ja/specdojo/samples/nfr-performance-sample.md +1 -1
  254. package/docs/ja/specdojo/samples/nfr-reliability-sample.md +1 -1
  255. package/docs/ja/specdojo/samples/nfr-security-safety-sample.md +1 -1
  256. package/docs/ja/specdojo/samples/nfr-usability-sample.md +1 -1
  257. package/docs/ja/specdojo/samples/ntp-sample.md +1 -1
  258. package/docs/ja/specdojo/samples/opd-sample.md +1 -1
  259. package/docs/ja/specdojo/samples/opr-sample.md +1 -1
  260. package/docs/ja/specdojo/samples/otp-index-sample.md +1 -1
  261. package/docs/ja/specdojo/samples/otp-sample.md +1 -1
  262. package/docs/ja/specdojo/samples/prj-stakeholder-register-sample.md +1 -1
  263. package/docs/ja/specdojo/samples/sac-sample.md +1 -1
  264. package/docs/ja/specdojo/samples/sf-index-sample.md +1 -1
  265. package/docs/ja/specdojo/samples/sf-sample.md +1 -1
  266. package/docs/ja/specdojo/samples/sld-sample.md +1 -1
  267. package/docs/ja/specdojo/samples/stc-index-sample.md +1 -1
  268. package/docs/ja/specdojo/samples/stc-sample.md +1 -1
  269. package/docs/ja/specdojo/samples/stsd-sample.md +1 -1
  270. package/docs/ja/specdojo/samples/sysd-critical-flows-sample.md +1 -1
  271. package/docs/ja/specdojo/samples/sysd-cross-cutting-policy-sample.md +1 -1
  272. package/docs/ja/specdojo/samples/sysd-index-sample.md +1 -1
  273. package/docs/ja/specdojo/samples/tsd-index-sample.md +22 -16
  274. package/docs/ja/specdojo/samples/tsd-sample.md +241 -21
  275. package/docs/ja/specdojo/samples/tsp-index-sample.md +1 -1
  276. package/docs/ja/specdojo/samples/uis-sample.md +1 -1
  277. package/docs/ja/specdojo/samples/utc-index-sample.md +1 -1
  278. package/docs/ja/specdojo/samples/utc-sample.md +1 -1
  279. package/docs/ja/specdojo/standards/document-metadata-standard.md +28 -3
  280. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +2 -0
  281. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +16 -11
  282. package/docs/ja/specdojo/standards/sample-authoring-standard.md +1 -0
  283. package/docs/ja/specdojo/templates/ifx-cmd-template.yaml +1 -1
  284. package/docs/ja/specdojo/templates/pjr-dependent-items-template.md +22 -0
  285. package/docs/ja/specdojo/templates/pjr-epic-items-template.md +22 -0
  286. package/docs/ja/specdojo/templates/pjr-epic-template.md +44 -0
  287. package/docs/ja/specdojo/templates/pjr-index-template.md +4 -2
  288. package/docs/specdojo/schemas/v1/bdd.schema.yaml +1 -1
  289. package/docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml +24 -16
  290. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +4 -1
  291. package/docs/specdojo/schemas/v1/exec-plan-frontmatter.schema.yaml +1 -1
  292. package/docs/specdojo/schemas/v1/gl.schema.yaml +8 -0
  293. package/docs/specdojo/schemas/v1/grade-pipeline-state.schema.yaml +1 -1
  294. package/docs/specdojo/schemas/v1/ifx-cmd.schema.yaml +5 -1
  295. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +2 -1
  296. package/docs/specdojo/schemas/v1/register-events.schema.yaml +20 -0
  297. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +73 -4
  298. package/docs/specdojo/schemas/v1/rulebook-frontmatter.schema.yaml +5 -0
  299. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +21 -3
  300. package/package.json +2 -2
  301. package/templates/antigravity/orchestrator.md +14 -9
  302. package/templates/claude/agents/specdojo-orchestrator.md +14 -9
  303. package/templates/codex/agents/specdojo-orchestrator.toml +14 -9
  304. package/templates/codex/orchestrator.md +14 -9
  305. package/templates/copilot/README.md +2 -1
  306. package/templates/devcontainer/devcontainer.json +1 -0
  307. package/templates/init-agent-members.yaml +46 -3
  308. package/templates/opencode/README.md +118 -14
  309. package/templates/opencode/agents/specdojo-orchestrator.md +15 -10
  310. package/templates/opencode/opencode.json +25 -0
@@ -1,38 +1,258 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:tsd-sample
4
- type: project
4
+ type: architecture
5
5
  status: draft
6
6
  rulebook: specdojo:tsd-rulebook
7
+ part_of:
8
+ - specdojo:tsd-index-sample
7
9
  ---
8
10
 
9
- # [技術スタック一覧](../rulebooks/tsd-rulebook.md) サンプル
11
+ # データベース(PostgreSQL / Prisma)技術スタック詳細定義(TSD)サンプル
10
12
 
11
- ## 1. 目的と適用範囲
13
+ 本書は、駄菓子屋きぬや販売管理システムにおいて、販売履歴、在庫データ、および常連客のつけ残高を安全かつ確実に永続化するためのデータベース基盤(PostgreSQL 16.x)および ORM(Prisma 5.x)の構成・設定・運用手順を定義した技術スタック詳細定義(TSD)のサンプルである。
12
14
 
13
- 本書は、システムで採用する技術(言語、フレームワーク、DB、メッセージ基盤、キャッシュ等)を、一覧として定義するための最小サンプルである。
15
+ ## 1. 概要と位置づけ
14
16
 
15
- ## 2. 入力情報
17
+ ### 1.1. 目的とビジネス価値
16
18
 
17
- - 対象: 駄菓子屋の販売管理システム
18
- - 前提: プロジェクト文脈は handbook の共通方針に準拠する
19
- - 参照: `../rulebooks/tsd-rulebook.md`
19
+ - **目的**: 駄菓子屋きぬやの業務運営で最重要となる「販売記録」「在庫データ」「常連客のつけ残高」をデータ破損や消失なく確実に永続化し、店頭タブレット端末から安定して読み書きできるデータ実行基盤を確立する。
20
+ - **ビジネス価値・運用上の利点**: 店主代表の記憶や紙の帳簿に依存していた販売・つけ管理をシステム化することで、つけ残高の確認時間を1分以内に短縮し、記録漏れによる金銭トラブルや人気商品の欠品・過剰在庫を防止する。
21
+ - **ユーザー価値**: 来店した地域の子どもたちや常連客に対し、正確な会計とつけ残高の確認を待たせることなく提供できる。
20
22
 
21
- ## 3. 記述内容
23
+ ### 1.2. 対象範囲と責務境界
22
24
 
23
- - 主な内容: プログラミング言語、フレームワーク、ミドルウェア など
24
- - 必須観点: 対象、条件、判定基準、責任者
25
+ | 区分 | 対象範囲・責務 | 主な内容 |
26
+ | -------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------- |
27
+ | スコープ内(対象) | データベース実行基盤と接続設定 | PostgreSQL 16.x のコンテナ構成、Prisma 5.x 連携設定、接続プール、永続ボリューム、バックアップ |
28
+ | スコープ内(対象) | 開発・本番の環境整合 | ローカル Docker 環境と本番コンテナ環境のパラメータ統一、マイグレーション適用手順 |
29
+ | スコープ外(対象外) | アプリケーション詳細設計 | 個別機能のビジネスロジック、詳細 API 仕様、SQL 全文([[specdojo:tsd-rulebook\|TSD ルールブック]] 禁止事項準拠) |
30
+ | スコープ外(対象外) | クライアント端末の管理 | 店頭タブレット端末の OS 設定、Wi-Fi 機器の物理配線およびネットワークハードウェア管理 |
25
31
 
26
- ## 4. 最小記述例
32
+ ### 1.3. 他文書との関係
27
33
 
28
- | 項目 | 値 | 備考 |
29
- | ------------ | ------------------------------------------------------------------------------------------------------ | ------------------------------------ |
30
- | ドキュメント | [技術スタック一覧](../rulebooks/tsd-rulebook.md) | 最小サンプル |
31
- | 目的 | システムで採用する技術(言語、フレームワーク、DB、メッセージ基盤、キャッシュ等)を、一覧として定義する | specdojo:deliverables-reference 準拠 |
32
- | 主な内容 | プログラミング言語、フレームワーク、ミドルウェア など | 要点のみ記載 |
34
+ - [[specdojo:tsd-index-sample|技術スタック一覧(TSD Index)サンプル]]: 駄菓子屋きぬや販売管理システム全体の採用技術一覧および各技術領域への導線(本書の上位一覧)。
35
+ - `tsd-hosting.md`: Fly.io 上のアプリケーション実行環境およびネットワーク基盤の構成定義(未作成のため仮置き)。
36
+ - `tsd-ci.md`: GitHub Actions による自動テストおよび本番デプロイワークフローの定義(未作成のため仮置き)。
33
37
 
34
- ## 5. 未解決事項
38
+ ### 1.4. 役割と責任
35
39
 
36
- | 論点 | 処理方針 |
37
- | -------------- | ------------------------ |
38
- | 要件詳細の補強 | 実案件適用時に具体化する |
40
+ - **所有権・アーキテクチャ責任(ARC)**: データベース構成、接続方式、技術制約、および全体アーキテクチャとの整合性担保。
41
+ - **業務要件確認(PO / 店主代表)**: 保存対象データ項目の充足性、運用停止許容時間、および業務継続性の承認。
42
+ - **実装・マイグレーション(DEV / 開発担当)**: Prisma スキーマ設計、マイグレーションスクリプト作成、および接続検証の実施。
43
+ - **運用・バックアップ管理(OPS / 運用アドバイザー)**: 定期バックアップ運用の設計、障害監視、およびリカバリ手順の確立。
44
+ - **技術助言(技術メンター)**: 構成設計のレビュー、接続プーリングおよびリソースチューニングへの助言。
45
+
46
+ ## 2. 対象環境と前提条件
47
+
48
+ ### 2.1. 実行環境と責務分界
49
+
50
+ | 実行場所 | 役割 | 実行ホスト / 基盤 | 主な実行プロセス |
51
+ | ---------- | -------------------------- | ------------------------------ | -------------------------------------------------- |
52
+ | 開発環境 | ローカル開発・検証 | 開発端末(macOS / Linux) | Docker Compose(PostgreSQL 16.x)、Node.js 22.x |
53
+ | 本番環境 | 永続データ保管・クエリ処理 | Fly.io(東京リージョン `nrt`) | Fly Postgres コンテナ、永続ボリューム(NVMe 10GB) |
54
+ | 接続元環境 | アプリケーションサーバー | Fly.io(東京リージョン `nrt`) | Next.js サーバープロセス、Prisma Client 5.x |
55
+
56
+ ### 2.2. 前提条件と必要リソース
57
+
58
+ - **ランタイム前提**: Node.js 22.x(サーバーサイド実行環境および開発環境)。
59
+ - **コンテナ前提**: Docker 26.x 以上、Docker Compose v2.x(ローカル環境用)。
60
+ - **CPU / メモリリソース**:
61
+ - 開発環境: 最小 512MB RAM、1 vCPU。
62
+ - 本番環境: 最小 1GB RAM、1 Shared CPU(店頭タブレット1台からの同時アクセスに対して十分な余裕を確保)。
63
+ - **ストレージ**: 10GB 永続ボリューム(年間データ増加量予測約 100MB に対して10年分以上の容量を確保)。
64
+ - **ネットワーク権限**: ポート 5432(PostgreSQL)への内部通信許可。外部インターネットへの直接ポート開放は禁止し、内部ネットワークまたは暗号化通信経由でのみアクセスを許可。
65
+
66
+ ## 3. 全体構成と接続経路
67
+
68
+ 店頭タブレット端末からデータベースに至る接続経路と責務境界を以下に示す。
69
+
70
+ ```mermaid
71
+ graph LR
72
+ subgraph Client["店頭端末(クライアント)"]
73
+ Tablet["店頭タブレット<br/>Next.js UI"]
74
+ end
75
+
76
+ subgraph Server["Fly.io アプリケーション環境"]
77
+ App["Next.js Server / API<br/>(Node.js 22.x)"]
78
+ PrismaClient["Prisma Client 5.x<br/>(Connection Pool)"]
79
+ end
80
+
81
+ subgraph Database["Fly.io データベース環境"]
82
+ PG["PostgreSQL 16.x<br/>(Port 5432)"]
83
+ Volume[("永続 Volume<br/>(10GB NVMe)")]
84
+ end
85
+
86
+ Tablet -->|HTTPS / 443| App
87
+ App --> PrismaClient
88
+ PrismaClient -->|"TCP / SSL (Port 5432)"| PG
89
+ PG --- Volume
90
+ ```
91
+
92
+ - 店頭タブレットは Web ブラウザを通じて Next.js サーバーに HTTPS(ポート 443)で接続し、データベースへ直接アクセスしない。
93
+ - Next.js サーバー内の Prisma Client がコネクションプールを介して PostgreSQL(ポート 5432)へ接続する。
94
+ - 本番環境では Fly.io のプライベート 6PN(WireGuard)メッシュネットワークを利用し、暗号化された安全な内部経路で通信を行う。
95
+
96
+ ## 4. 採用技術と設定値
97
+
98
+ ### 4.1. 採用設定一覧
99
+
100
+ PostgreSQL および Prisma の採用設定を以下に定義する。
101
+
102
+ | 対象・用途 | 設定項目 | 採用値・版 | 適用範囲 | 理由・制約 | 反映・確認方法 |
103
+ | ------------------ | ------------------------------------- | ---------------- | ---------------- | --------------------------------------------------------------------- | --------------------------------------- |
104
+ | DB エンジン | バージョン | PostgreSQL 16.x | 全環境 | 長期サポート版であり、JSON 処理性能と耐障害性に優れるため | `SELECT version();` で確認 |
105
+ | 接続ライブラリ | バージョン | Prisma 5.x | 全環境 | 型安全なクエリ生成と TypeScript 5.x との親和性のため | `package.json` および `npx prisma -v` |
106
+ | 文字コード | `client_encoding` / `server_encoding` | `UTF8` | 全環境 | 商品名や常連客名の日本語文字化けを防止するため | `SHOW server_encoding;` |
107
+ | タイムゾーン | `timezone` | `Asia/Tokyo` | 全環境 | 店舗の営業時間および日次売上集計を日本標準時で統一するため | `SHOW timezone;` |
108
+ | 接続数制限 | `max_connections` | `50` | 本番環境 | メモリ枯渇を防ぎつつ、Web サーバーからの同時接続を許容するため | `SHOW max_connections;` |
109
+ | コネクションプール | `connection_limit` | `10` | アプリケーション | 店舗端末1台運用のアクセス規模に適合させ、余剰接続を抑制するため | `DATABASE_URL` のクエリパラメータで設定 |
110
+ | 共有バッファ | `shared_buffers` | `256MB` | 本番環境 | 割り当てメモリ 1GB のうち 25% をデータキャッシュに充当するため | `SHOW shared_buffers;` |
111
+ | スロークエリ監視 | `log_min_duration_statement` | `1000`(ミリ秒) | 本番環境 | 1秒以上を要するクエリを検知し、店頭端末の画面フリーズを未然に防ぐため | サーバーログ出力を確認 |
112
+
113
+ ### 4.2. 採用値・推奨値・未決事項の区別
114
+
115
+ - **採用値(固定)**: PostgreSQL 16.x、Prisma 5.x、文字コード `UTF8`、タイムゾーン `Asia/Tokyo`。店舗の基本仕様として確定。
116
+ - **推奨値(調整可能)**: `connection_limit=10`、`shared_buffers=256MB`。小規模店舗での運用実績を踏まえて推奨するが、アクセス傾向に応じて見直し可能。
117
+ - **未決事項(検討中)**: _UNDECIDED_: 年末年始や繁忙期における一時的なメモリ拡張ポリシー(日次売上件数の実測推移をもとに運用フェーズで判断)。
118
+
119
+ ### 4.3. 接続情報と機密情報の管理
120
+
121
+ - 秘密情報(パスワード・接続トークン等)はリポジトリのソースコードや設定ファイルに直接記載しない。
122
+ - 接続文字列の書式(プレースホルダー):
123
+ - 開発環境: `postgresql://<DEV_USER>:<DEV_PASSWORD>@localhost:5432/<DEV_DB>?schema=public`
124
+ - 本番環境: `postgresql://<PROD_USER>:<PROD_PASSWORD>@<PROD_HOST>:5432/<PROD_DB>?sslmode=require&connection_limit=10`
125
+ - 機密情報の管理方法:
126
+ - ローカル開発環境: `.env` ファイルに記述し、`.gitignore` で Git 管理から除外。テンプレートは `.env.example` で共有する。
127
+ - 本番環境: Fly.io のシークレット管理(`fly secrets set DATABASE_URL=...`)に暗号化保存し、環境変数としてコンテナに注入する。
128
+
129
+ ## 5. 導入と初期設定
130
+
131
+ ### 5.1. 開発環境の初期構築手順
132
+
133
+ ローカル開発環境でのコンテナ起動からマイグレーション適用までの手順を示す。
134
+
135
+ 1. **DB コンテナの起動**:
136
+
137
+ 作業ディレクトリ直下の Docker Compose を使用してコンテナを起動する。
138
+
139
+ ```bash
140
+ # PostgreSQL コンテナの起動
141
+ docker compose up -d postgres
142
+ ```
143
+
144
+ 2. **環境変数ファイルの準備**:
145
+
146
+ テンプレートから `.env` を作成し、接続パラメータを設定する。
147
+
148
+ ```bash
149
+ cp .env.example .env
150
+ # .env 内の DATABASE_URL をローカル接続情報に合わせて編集
151
+ ```
152
+
153
+ 3. **Prisma スキーマのマイグレーション適用**:
154
+
155
+ 定義済みスキーマからマイグレーションを実行し、テーブル群を生成する。
156
+
157
+ ```bash
158
+ npx prisma migrate dev --name init
159
+ ```
160
+
161
+ 4. **初期シードデータの投入**:
162
+
163
+ 駄菓子商品マスターおよび初期店舗設定データを投入する。
164
+
165
+ ```bash
166
+ npx prisma db seed
167
+ ```
168
+
169
+ ### 5.2. スキーマ変更とマイグレーションの運用
170
+
171
+ - スキーマ変更時は必ずマイグレーションファイルを作成し、バージョン管理に含める。
172
+ - **変更影響と互換性方針**:
173
+ - 本番稼働中の列の削除や型変更は即時実行せず、互換フェーズ(新列追加 → アプリケーション移行 → 旧列削除)の 2 段階で適用する。
174
+ - 本番デプロイ時は CI/CD パイプライン内で `npx prisma migrate deploy` を自動実行し、マイグレーション適用の成否を確認した後にアプリケーションコンテナを切り替える。
175
+
176
+ ## 6. 動作確認と切り分け
177
+
178
+ PostgreSQL および Prisma の正常性を確認するための手順と判定基準を以下に定義する。
179
+
180
+ ### 6.1. 動作確認一覧表
181
+
182
+ | 確認対象 | 実行場所・方法 | 期待結果 | 失敗時の確認先 |
183
+ | --------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
184
+ | コンテナ起動状態 | 開発端末: `docker compose ps postgres`<br/>本番環境: `fly status --app kinuyo-db` | 状態が `Up` または `running` であり、予期せぬ再起動が発生していないこと | Docker デーモンの稼働状態、Fly.io プラットフォームステータス、コンテナ割り当てメモリ量 |
185
+ | ネットワーク疎通 | 開発端末 / サーバー: `nc -zv <HOST> 5432` | ポート 5432 への接続が `open` または `succeeded` と表示されること | ファイアウォール設定、Fly.io 内部プライベートネットワーク設定、セキュリティグループ |
186
+ | DB 認証・接続 | 開発端末 / サーバー: `psql -h <HOST> -U <USER> -d <DB> -c "SELECT 1;"` | 実行結果として `1` が返却されること | `DATABASE_URL` のユーザー名・パスワード、PostgreSQL の `pg_hba.conf` 認証設定 |
187
+ | Prisma マイグレーション状態 | アプリケーション環境: `npx prisma migrate status` | `Database schema is up to date` と表示され、未適用のマイグレーションがないこと | `prisma/migrations` ディレクトリの内容、DB 内の `_prisma_migrations` テーブル |
188
+ | CRUD 動作検証 | アプリケーション環境: 単体テスト実行 `npm run test:unit -- tests/db/connection.test.ts` | テスト用レコード(商品・つけ残高)の作成・取得・更新・削除がすべて PASS すること | Prisma Client 生成状態(`npx prisma generate`)、トランザクションタイムアウト設定 |
189
+
190
+ ## 7. 継続利用と運用・バックアップ
191
+
192
+ ### 7.1. データの永続化と再起動時の挙動
193
+
194
+ - Fly.io の永続ボリューム(10GB)を `/var/lib/postgresql/data` にマウントして使用する。
195
+ - コンテナの再デプロイ、再起動、またはホストマシンのメンテナンス時にもデータは失われず保持される。
196
+ - 一時的なメモリ領域(セッション情報、クエリキャッシュ)は再起動時に初期化されるが、販売記録・つけ残高の正本データには影響を与えない。
197
+
198
+ ### 7.2. 定期バックアップ手順
199
+
200
+ 日次でのデータ保護を行うため、以下のバックアップ運用を実施する。
201
+
202
+ 1. **日次論理バックアップ**:
203
+
204
+ 深夜の店舗休業時間帯(午前 3:00)に自動スクリプトで `pg_dump` を実行する。
205
+
206
+ ```bash
207
+ # バックアップ実行コマンド例
208
+ pg_dump -h <HOST> -U <USER> -d <DB> -F c -b -v -f "/backups/kinuyo-db-$(date +%Y%m%d).dump"
209
+ ```
210
+
211
+ 2. **バックアップ保管ポリシー**:
212
+
213
+ 生成されたダンプファイルは暗号化のうえ、外部クラウドストレージへ自動転送する。日次データは過去30日分、月末データは過去1年分を保持する。
214
+
215
+ 3. **リカバリ手順**:
216
+
217
+ データ破損や誤操作発生時は、以下の手順で特定時点のバックアップからリストアする。
218
+
219
+ ```bash
220
+ # リストア実行コマンド例
221
+ pg_restore -h <HOST> -U <USER> -d <DB> -v --clean --if-exists "/backups/kinuyo-db-<TARGET_DATE>.dump"
222
+ ```
223
+
224
+ ## 8. 制約事項とトラブルシュート
225
+
226
+ ### 8.1. 既知の制約事項
227
+
228
+ - **オフライン時の制限**: 店頭タブレットがネットワーク不通となった場合、PostgreSQL への直接書き込みは行えない。端末側ブラウザの一時退避領域(IndexedDB)に販売記録を保持し、再接続時に順次同期する構成を前提とする。
229
+ - **同時接続数上限**: 本構成の同時接続数は最大 50(実効推奨 10)に制限されている。店頭端末以外の外部ツールや分析スクリプトを大量並行実行してはならない。
230
+
231
+ ### 8.2. トラブルシューティングガイド
232
+
233
+ 障害発生時の主な症状、原因、および切り分け・回避手順を以下に示す。
234
+
235
+ | 症状 | 主な原因 | 切り分け手順 | 回避・復旧方法 |
236
+ | ------------------------------------------------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
237
+ | 接続タイムアウト<br/>(`P1001: Can't reach database server`) | DB コンテナの停止、または内部ネットワークの疎通不全 | 1. `fly status` で DB コンテナの稼働を確認<br/>2. `nc -zv` でポート 5432 の疎通を確認 | コンテナが停止している場合は `fly apps restart kinuyo-db` で再起動する。ネットワーク不通時は Fly.io ステータスを確認する |
238
+ | マイグレーションロックエラー<br/>(`Migration is locked`) | 前回のマイグレーション失敗によるロックの残留 | `_prisma_migrations` テーブルの `applied_steps_count` と `finished_at` を確認 | `npx prisma migrate resolve` を実行してロックを解除し、不整合のあるステップを手動で調整する |
239
+ | コネクション枯渇<br/>(`remaining connection slots are reserved`) | ゾンビ接続の残留、または接続リーク | `SELECT count(*), state FROM pg_stat_activity GROUP BY state;` を実行 | アイドル状態の不要な接続を `SELECT pg_terminate_backend(pid);` で切断し、Prisma Client の接続解放漏れを修正する |
240
+ | メモリ不足停止<br/>(`Out of Memory: Killed process`) | 大量データの一括取得、またはメモリリーク | `fly logs` で `OOM killed` メッセージの有無を確認 | 取得クエリにページネーション(`take` / `skip`)を適用し、必要に応じて Fly.io のコンテナメモリを 2GB へスケールアップする |
241
+
242
+ ## 9. 未解決事項と解決経路
243
+
244
+ 本定義を `ready` ステータスへ昇格させるために解決すべき課題および運用上の未決事項を以下に示す。
245
+
246
+ ### 9.1. 未解決事項一覧表
247
+
248
+ | 課題 ID | 論点 | 影響 | 意思決定基準・判断期日 | 解決経路・アクション | 担当 Role |
249
+ | ---------- | ---------------------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | --------- |
250
+ | `ISSUE-01` | 店頭オフライン時のつけ・販売データ同期プロトコルの策定 | ネットワーク不通時に店頭で記録したつけ残高の更新順序と競合解決 | 同期失敗率 0.1% 未満をテスト環境で実証(期日: 結合テスト着手前) | DEV が端末側 IndexedDB 一時退避と復旧時の一括トランザクション送信プロトタイプを作成し、ARC がレビュー | DEV / ARC |
251
+ | `ISSUE-02` | 本番自動バックアップ保管先の外部クラウドストレージ選定 | 障害時の復旧即時性と長期保管の月額運用コスト | 月額費用 500 円以内で暗号化・ライフサイクル設定が可能であること(期日: 本番運用開始2週間前) | OPS が Cloudflare R2 および AWS S3 を比較検証し、PO(店主代表)の費用承認を得る | OPS / PO |
252
+ | `ISSUE-03` | 繁忙期(駄菓子屋祭りイベント等)における一時的スケールアップ基準 | 集中アクセス時の店頭画面レスポンス遅延の防止 | 店頭端末の会計完了待機時間が 3 秒を超える確率を 0% に抑制(期日: 総合リハーサル前) | 疑似負荷テストを実施し、CPU 使用率 80% 超過時のメモリ増設手順(1GB → 2GB)を OPS が手順化 | OPS / DEV |
253
+
254
+ ### 9.2. ready ステータス達成基準
255
+
256
+ - `ISSUE-01` から `ISSUE-03` について、合意された解決経路に沿って検証が完了し、担当 Role による合意が得られていること。
257
+ - 「6. 動作確認と切り分け」に定義されたすべての検証項目がステージング環境で PASS し、エラーなく再現可能であることが確認されていること。
258
+ - ARC によるアーキテクチャレビューおよび PO による運用方針の最終承認が完了していること。
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:tsp-index-sample
4
- type: project
4
+ type: test
5
5
  status: draft
6
6
  rulebook: specdojo:tsp-index-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:uis-sample
4
- type: project
4
+ type: ui
5
5
  status: draft
6
6
  rulebook: specdojo:uis-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:utc-index-sample
4
- type: project
4
+ type: test
5
5
  status: draft
6
6
  rulebook: specdojo:utc-index-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:utc-sample
4
- type: project
4
+ type: test
5
5
  status: draft
6
6
  rulebook: specdojo:utc-rulebook
7
7
  ---
@@ -16,7 +16,7 @@ Markdown の Frontmatter と YAML・JSON の構造化メタデータに関する
16
16
  - 共通原則: Frontmatter を持つすべての Markdown ドキュメント
17
17
  - 独立 YAML データファイル向け規約: SpecDojo スキーマ(`docs/specdojo/schemas/v1/`)を持つ YAML 成果物(`dct-*.yaml` / `pm-*.yaml` / `sch-*.yaml` / `bdd-*.yaml` など)
18
18
  - JSON データファイル向け規約: SpecDojo が管理する JSON 文書、実行イベント、設定、インデックス、生成物
19
- - 成果物向け詳細規約: `project` / `flow` / `rule` / `data` / `ui` / `api` / `architecture` / `test` / `operations` / `template` / `sample`
19
+ - 成果物向け詳細規約: `project` / `requirement` / `glossary` / `flow` / `rule` / `data` / `ui` / `api` / `architecture` / `test` / `operations` / `template`
20
20
  - 成果物スキーマ: [deliverable-frontmatter.schema.yaml](../../../specdojo/schemas/v1/deliverable-frontmatter.schema.yaml)
21
21
 
22
22
  `rulebook` / `recipe` / `guide` / `reference` / `standard` / `philosophy` は専用スキーマを持つため、成果物向け詳細規約の対象外とします。それぞれの追加規約は次を正本とします。
@@ -36,6 +36,31 @@ Markdown の Frontmatter と YAML・JSON の構造化メタデータに関する
36
36
  - `id` は共通スキーマの `idRef` に従い、`^[a-z0-9][a-z0-9-:]*$` に一致させる。
37
37
  - npm package が所有する型(Kata)の文書の `id` は `<authority>:<local-id>` とし、SpecDojo core は `specdojo:` を使用する。これは Frontmatter の親キー `specdojo:` とは別に、ID値の所有元を表す namespace である。
38
38
  - `type` は各ドキュメント種別のスキーマに定義された値を使用する。
39
+ - 成果物の `type` は次の意味で選び、準拠する rulebook の `specdojo.deliverable_type` を正本とする。index も扱う内容と同じ分類にする。
40
+
41
+ | 値 | 意味 |
42
+ | -------------- | ---------------------------------------------------------------------------- |
43
+ | `project` | プロジェクトの計画・体制・登録簿・進捗・管理ビュー(prj・pm・dct・tml など) |
44
+ | `requirement` | システム機能、業務イベントの要求、非機能要件、業務・システムの受入基準 |
45
+ | `glossary` | 用語と定義を管理する用語集 |
46
+ | `flow` | 業務フロー・プロセス・概念データフロー |
47
+ | `rule` | 業務の判断条件・規則 |
48
+ | `data` | データ構造・概念モデル・状態・保管・データ移行設計 |
49
+ | `ui` | 画面・帳票の仕様 |
50
+ | `api` | API・コマンド・ファイル・メッセージなど外部 I/F の契約 |
51
+ | `architecture` | システム構成・設計・技術選定 |
52
+ | `test` | テスト戦略・設計・ケース・実施計画 |
53
+ | `operations` | 運用設計・手順・本番切替・運用移管 |
54
+
55
+ - `project` をプロダクト仕様の受け皿にしない。sample は見本にする成果物の `type` を使い、`id` とファイル名の `-sample` で識別する。`template` はテンプレート自身の種別であり、生成物の種別ではない。
56
+ - `lint:fm` の frontmatter 検査では、Markdown 成果物・sample の `specdojo.type` と、テンプレートの `specdojo.frontmatter_template.specdojo.type` をそれぞれの `rulebook` の宣言と照合する。宣言と異なる値(従来の `project` や `sample` を含む)は即時エラーとし、宣言された置き換え先を表示する。`rulebook: none` は照合対象外とする。
57
+ - 照合は主 rulebook の宣言を使い、`includes` はたどらない。rulebook は完全 ID で解決し、同じ ID のローカル文書を同梱文書より優先する。解決不能・曖昧・宣言欠落は検査エラーとする。未修飾 ID は一意に解決できる場合のみ許容する。
58
+ - `validate:schema:yaml`(`yaml-schema --modeline`)と `validate:schema:file` は、YAML 成果物・sample のトップレベルまたは `x-spec-meta` の `type` と、テンプレートの `metadata_template.type` を主 rulebook の宣言と照合する。`specdojo-schema: none` / `validate=false` は構造の検証だけを省略し、メタ情報の照合は省略しない。平坦な YAML catalog テンプレートは生成物のメタ情報雛形を持たないため、その `type: template` は照合しない。
59
+ - YAML メタ情報の旧値 `domain` / `command` / `message` は `rulebook: none` の場合もエラーとし、それぞれ `data` / `api` / `api` への置き換えを表示する。本文中のデータ型や CloudEvents のイベント種別は対象外とする。
60
+ - YAML の表示用ページ(`generated/` 配下)は元 YAML のトップレベルまたは `x-spec-meta` の `type` を引き継ぐ。配置パスから分類を補わず、欠落も補完しない。生成ページも `lint:fm` の宣言照合対象とする。ただし、ジョブ定義・評価記録など `type` を持たない YAML の表示用ページは成果物 Frontmatter を付けずに生成する。これらの表示ページは Markdown の Frontmatter 必須原則の対象外とし、正本 YAML の構造・メタ情報は対応する schema と YAML 検証を正本とする。
61
+ - 成果物として成り立つ文書の `type` は、中身の種類(`project` / `flow` / `data` など)を表す。成果物として成り立たない実践の型(rulebook / recipe / template など)の `type` は、その役割を表す。
62
+ - sample は完成した成果物の最小例であり、Markdown・YAML・JSON とも、`type` には見本にする成果物の type を書く。sample であることは `id` とファイル名の `-sample`、`samples/` への配置、対応 rulebook の `sample` 宣言で表す。
63
+ - sample のメタ情報と本文は成果物と同じ形式にし、文書索引で実物の成果物と衝突しないよう `id` を区別する。既存の `type: sample` は schema 上の互換値として保持するが、新規作成・更新では使用しない。rulebook を持つ Markdown・YAML sample は宣言との照合でエラーになるため、宣言された成果物の type へ移行する。
39
64
  - `status` は `draft` / `ready` / `deprecated` のいずれかとする。
40
65
  - ドキュメント名は Frontmatter ではなく本文先頭の H1 に記述する。
41
66
  - `specdojo:` 名前空間の対象は Markdown Frontmatter のみとする。独立 YAML データファイル(`dct-*.yaml` / `pm-*.yaml` / `sch-*.yaml` など)は Markdown ではなく他ツールとの同居も無いため、名前空間化せずトップレベルに項目を置く。
@@ -126,7 +151,7 @@ specdojo:
126
151
  - `rulebook` を必須とし、準拠する rulebook の ID を指定する。該当する rulebook がない場合のみ `none` を許可する(成果物の必須項目と同じ制約)。
127
152
  - YAML catalog テンプレート(`dct-*-template.yaml`)では、`title` / `rulebook` は生成物側フィールドとして生成物の値を平坦に記述する(テンプレート自身のメタ情報と生成物 Frontmatter の分離を参照)。それ以外のテンプレート(`*-template.yaml`)では、`title` はテンプレート自身の名前を実値で記述し、生成物のメタ情報は `metadata_template` に記述する(本標準 `生成物メタ情報雛形(metadata_template)`)。
128
153
  - 上記以外の項目(`based_on` / `supersedes` / `version` / `project_id` など)の許可項目と型は各スキーマを正本とする。
129
- - OpenAPI / AsyncAPI など外部標準形式の YAML(`ifx-*` 等)は本規約の対象外とし、`info.title` や `x-spec-meta` など各形式の慣行に従う。
154
+ - OpenAPI / AsyncAPI など外部標準形式の YAML(`ifx-*` 等)は配置について各形式の慣行に従い、表題は `info.title`、`id` / `type` / `status` / `rulebook` は `x-spec-meta` に置く。`type` は主 rulebook の宣言と照合する。
130
155
 
131
156
  ```yaml
132
157
  id: prj-0001:pm-roles
@@ -251,7 +276,7 @@ specdojo:
251
276
 
252
277
  ### 6.2. 継続品質評価(`grade`)
253
278
 
254
- Markdown 文書の最新の継続品質評価は、プロジェクトの `<execution_path>/grade/results/<doc-id>.yaml` にサイドカーとして記録します。成果物の Frontmatter と本文には grade や finding を書き込みません。サイドカーは最新状態のスナップショットであり、`specdojo grade apply` は文書 ID ごとの同じファイルを冪等に上書きします。履歴は Job Run と evidence、合意形成は review result が担います。成果物の現在品質を参照するときは、サイドカーの `content_hash` が現在のファイル全体と一致することを確認します。
279
+ Markdown 文書の最新の継続品質評価は、プロジェクトの `<execution_path>/grade/results/` 配下にサイドカーとして記録します。本リポジトリの文書は `<doc-id>.yaml`、`project.repos` に宣言したリポジトリの文書は `<repo 名>/<doc-id>.yaml` に保存し、`<repo 名>` には `repos[].name`、ファイル名には文書 ID の `:` を `.` に置き換えた値を使います。成果物の Frontmatter と本文には grade や finding を書き込みません。サイドカーは最新状態のスナップショットであり、`specdojo grade apply` は同じリポジトリ・文書 ID のファイルを冪等に上書きします。履歴は Job Run と evidence、合意形成は review result が担います。成果物の現在品質を参照するときは、サイドカーの `content_hash` が現在のファイル全体と一致することを確認します。
255
280
 
256
281
  | 項目 | 意味 |
257
282
  | ------------------- | ------------------------------------------------------------------------------------ |
@@ -442,6 +442,8 @@ IDには、次の情報を含めない。
442
442
  - `<subject>`: 文書の主題を表す名詞句
443
443
  - `<type-suffix>`: `guide`、`standard`、`reference`、`philosophy`、`rulebook`、`recipe`、`sample`、`template`
444
444
 
445
+ sample の種類の判定は `id` の local-id の末尾 `-sample` で行います。`type` は見本にする成果物の type とします(正本: [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]])。この規則は利用者の authority の sample にも適用します。
446
+
445
447
  - package の所有元は `specdojo:` のような authority で表し、local-id に `specdojo-` のような所属接頭辞を重ねない。
446
448
  - ただし SpecDojo 自体を主題とする文書は、主題語として `specdojo` を用いる。
447
449
 
@@ -32,22 +32,26 @@ Rulebook Authoring Standard
32
32
  - ファイル名は `<prefix>-rulebook.md` とする。
33
33
  - `id` / `type` / `status` を必須とし、共通原則は [document-metadata-standard.md](document-metadata-standard.md) に従う。
34
34
  - `type` は `rulebook` 固定とする。
35
+ - `deliverable_type` は必須とし、扱う成果物の `type` を一つ宣言する。値の意味は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従う。`template` / `sample` は成果物の分類ではないため宣言しない。
35
36
  - `id` はauthority、英小文字・数字・ハイフンで構成し、一意にする(正確な制約は参照スキーマに従う)。
36
37
  - `status` は `draft` / `ready` / `deprecated` のいずれかとする。
37
38
 
38
- | 項目 | 必須 | 説明 |
39
- | ------------- | ---- | ---------------------------------------------------------------------------------------------------- |
40
- | id | ○ | 同梱は `specdojo:<prefix>-rulebook`、利用者作成は `<kata_authority>:<prefix>-rulebook` 形式の一意 ID |
41
- | type | ○ | `rulebook` 固定 |
42
- | status | ○ | `draft` / `ready` / `deprecated` |
43
- | target_format | 任意 | 対象ドキュメントのフォーマット(`yaml` / `json` / `markdown`) |
44
- | recipe | 任意 | 対応する recipe の完全 ID、`undecided`、`not-needed` |
45
- | sample | 任意 | 対応する sample の完全 ID または ID 配列、上記2状態 |
46
- | template | 任意 | 対応する template の完全 ID、`undecided`、`not-needed` |
47
- | based_on | 任意 | 上位規約や根拠ドキュメント |
48
- | supersedes | 任意 | 置き換え関係 |
39
+ | 項目 | 必須 | 説明 |
40
+ | ------------------ | ---- | --------------------------------------------------------------------------------------------------------------------------------------- |
41
+ | id | ○ | 同梱は `specdojo:<prefix>-rulebook`、利用者作成は `<kata_authority>:<prefix>-rulebook` 形式の一意 ID |
42
+ | type | ○ | `rulebook` 固定 |
43
+ | `deliverable_type` | ○ | 成果物の種別。`project` / `requirement` / `glossary` / `flow` / `rule` / `data` / `ui` / `api` / `architecture` / `test` / `operations` |
44
+ | status | ○ | `draft` / `ready` / `deprecated` |
45
+ | target_format | 任意 | 対象ドキュメントのフォーマット(`yaml` / `json` / `markdown`) |
46
+ | recipe | 任意 | 対応する recipe の完全 ID、`undecided`、`not-needed` |
47
+ | sample | 任意 | 対応する sample の完全 ID または ID 配列、上記2状態 |
48
+ | template | 任意 | 対応する template の完全 ID、`undecided`、`not-needed` |
49
+ | based_on | 任意 | 上位規約や根拠ドキュメント |
50
+ | supersedes | 任意 | 置き換え関係 |
49
51
 
50
52
  - `target_format` が未記載の場合は markdown を対象とみなす。
53
+ - `deliverable_type` は format・成熟度によらず全 rulebook に必要とする。index は扱う内容で分類し、`project` はプロジェクトの管理文書に限る。Mermaid など `includes` で適用される記法部品も、扱う成果物の種別を宣言する。
54
+ - `lint:fm` は Markdown 成果物・sample・テンプレートの生成物 Frontmatter(`frontmatter_template`)を、主 rulebook の宣言と照合する。テンプレート自身の `type: template` は照合しない。宣言との不一致、宣言欠落、参照の解決不能・曖昧さはエラーとし、不一致には宣言値を示す。YAML 成果物・sample とテンプレートの `metadata_template` は YAML schema 検証時に同じ宣言と照合し、外部形式の `x-spec-meta` も対象とする。構造検証を省略する指示でも照合は省略しない。YAML の表示用ページは正本の `type` を引き継ぎ、`lint:fm` の照合対象とする。
51
55
  - `recipe` / `sample` / `template` は要否と所在の正本であり、`undecided` は要否未判断、項目省略は必要だが未整備、完全 ID は必要かつ整備済み、`not-needed` は不要を表す。
52
56
  - 完全 ID は `fully-guided` / `recipe-guided` の plan 生成で参照先パスの解決に使う(rulebook を参照ハブとする)。命名規約に従う場合も明示的に宣言し、宣言された参照先ファイルが存在しないと `exec validate` が警告する。`sample` の拡張子は `target_format` に従う。
53
57
  - 同じ rulebook 系統に複数の完成例がある場合、`sample` を ID 配列で宣言する。配列の先頭を既定例として使う。
@@ -60,6 +64,7 @@ Rulebook Authoring Standard
60
64
  specdojo:
61
65
  id: specdojo:imp-business-rulebook
62
66
  type: rulebook
67
+ deliverable_type: project
63
68
  status: draft
64
69
  ---
65
70
  ```
@@ -105,6 +105,7 @@ sample は実在プロジェクトの記録ではありません。記載値は
105
105
 
106
106
  - ファイル名は `<prefix>-sample.md` / `<prefix>-sample.yaml` / `<prefix>-sample.json` とし、対応 rulebook の `target_format` に合わせる。
107
107
  - `target_format` が未記載の場合は markdown を対象とみなす。
108
+ - [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従い、`type` は見本にする成果物の type とする。sample であることは `id` とファイル名の `-sample` で表す。
108
109
  - Markdown の場合、H1 はファイル内で 1 つだけとし、`id` / `type` / `status` / `rulebook` を含む Frontmatter を先頭に置く。
109
110
  - YAML / JSON の場合、対応 rulebook が定める先頭メタ項目・ルートキー・必須キーを満たす。
110
111
 
@@ -10,7 +10,7 @@ title: 外部コマンド連携仕様テンプレート
10
10
  rulebook: none
11
11
  metadata_template:
12
12
  id: ifx-cmd-_TERM_
13
- type: command
13
+ type: api
14
14
  status: draft
15
15
  title: _COMMAND_SPEC_TITLE_
16
16
  rulebook: specdojo:ifx-cmd-rulebook
@@ -0,0 +1,22 @@
1
+ ---
2
+ specdojo:
3
+ id: specdojo:pjr-dependent-items-template
4
+ type: template
5
+ status: draft
6
+ frontmatter_template:
7
+ specdojo:
8
+ id: _PROJECT_ID_:pjr-dependent-items
9
+ type: project
10
+ status: ready
11
+ rulebook: specdojo:pjr-rulebook
12
+ part_of:
13
+ - _PROJECT_ID_:pjr-index
14
+ ---
15
+
16
+ # 登録項目の実行依存
17
+
18
+ > このファイルは個票の `depends_on` から生成された派生ビューです。正本は個票の Frontmatter であり、このファイルは再生成可能です。
19
+
20
+ ## 1. 先行項目から後続項目を辿る
21
+
22
+ <!-- specdojo:view-slot=derived-items -->
@@ -0,0 +1,22 @@
1
+ ---
2
+ specdojo:
3
+ id: specdojo:pjr-epic-items-template
4
+ type: template
5
+ status: draft
6
+ frontmatter_template:
7
+ specdojo:
8
+ id: _PROJECT_ID_:pjr-epic-items
9
+ type: project
10
+ status: draft
11
+ rulebook: specdojo:pjr-rulebook
12
+ part_of:
13
+ - _PROJECT_ID_:pjr-index
14
+ ---
15
+
16
+ # epic ごとの子項目
17
+
18
+ > 個票の `derived_from` から生成した直接の子項目と現在の状態です。正本は個票の Frontmatter です。子の完了だけでは epic を自動 close しません。
19
+
20
+ ## 1. epic 別の一覧
21
+
22
+ <!-- specdojo:view-slot=epic-items -->
@@ -0,0 +1,44 @@
1
+ ---
2
+ specdojo:
3
+ id: specdojo:pjr-epic-template
4
+ type: template
5
+ status: draft
6
+ frontmatter_template:
7
+ specdojo:
8
+ id: _PJR_DOCUMENT_ID_
9
+ type: project
10
+ status: draft
11
+ rulebook: specdojo:pjr-rulebook
12
+ part_of:
13
+ - _PROJECT_ID_:pjr-index
14
+ item_type: epic
15
+ track: track-id
16
+ item_status: open
17
+ priority: medium
18
+ ---
19
+
20
+ # _PJR-XXXX_ _EPIC_TITLE_
21
+
22
+ ## 1. 概要
23
+
24
+ _TODO_: track で達成する目的と着手の理由を記載する。
25
+
26
+ ## 2. 範囲(track と domain)
27
+
28
+ _TODO_: Frontmatter の `track` が担う範囲と対象 domain、対象外の境界を記載する。
29
+
30
+ ## 3. 完了の判断の基準
31
+
32
+ - _TODO_: 子項目と schedule を確認して、人が完了を判断できる基準を記載する。
33
+
34
+ ## 4. 子項目
35
+
36
+ 子 todo は `register add --type todo --from <epic-id>` で起票する。現在の一覧と状態は `register build` が生成する epic 別ビューで確認する。
37
+
38
+ ## 5. 対応結果
39
+
40
+ _TODO_: 完了を判断した根拠と残課題を記載する。未完了の場合は `-` とする。
41
+
42
+ ## 6. 関連ドキュメント
43
+
44
+ - _TODO_: 根拠・影響先・追跡先を文書 ID で記載する。
@@ -27,8 +27,8 @@ Project Register
27
27
  ## 1. 登録項目一覧
28
28
 
29
29
  <!-- prettier-ignore -->
30
- | ID | ステータス | タイトル | 説明 | 分類 | 優先度 | 担当 | 登録日 | 期限 | 完了日 | 結論 | 個票 |
31
- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
30
+ | ID | ステータス | タイトル | 説明 | 分類 | 優先度 | 担当 | 登録日 | 期限 | 完了日 | 結論 | 個票 | `depends_on` |
31
+ | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
32
32
 
33
33
  ## 2. 派生ビュー
34
34
 
@@ -41,6 +41,8 @@ Project Register
41
41
  - [[pjr-views-by-priority|台帳ビュー(優先度別)]]
42
42
  - [[pjr-views-by-owner|台帳ビュー(担当者別)]]
43
43
  - [[pjr-derived-items|登録項目の派生関係]]
44
+ - [[_PROJECT_ID_:pjr-dependent-items|登録項目の実行依存]]
45
+ - [[_PROJECT_ID_:pjr-epic-items|epic ごとの子項目]]
44
46
 
45
47
  ### 2.2. controls 全体の派生管理ビュー
46
48
 
@@ -18,7 +18,7 @@ properties:
18
18
 
19
19
  type:
20
20
  type: string
21
- const: "domain"
21
+ const: "data"
22
22
 
23
23
  title:
24
24
  type: string