specdojo 0.4.7 → 0.6.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 (312) hide show
  1. package/.github/agents/specdojo-orchestrator.md +16 -9
  2. package/CHANGELOG.md +106 -0
  3. package/dist/catalog/generate.js +144 -13
  4. package/dist/commands/init.js +4 -0
  5. package/dist/commands/night-orchestrator.js +33 -4
  6. package/dist/dashboard/dashboard.js +5 -6
  7. package/dist/dashboard/timeline-build.js +5 -1
  8. package/dist/dashboard/timeline.js +6 -3
  9. package/dist/deliverable/deliverable.js +77 -4
  10. package/dist/docs/yaml-pages.js +17 -17
  11. package/dist/exec/core.js +3 -0
  12. package/dist/exec/parent-validation.js +7 -0
  13. package/dist/exec/pipeline-state.js +5 -2
  14. package/dist/exec/plans-core.js +49 -3
  15. package/dist/exec/plans-generation.js +48 -8
  16. package/dist/exec/plans-grade-findings.js +16 -0
  17. package/dist/exec/plans-planning.js +43 -0
  18. package/dist/exec/plans-storage.js +6 -2
  19. package/dist/exec/product-branch-records.js +105 -0
  20. package/dist/exec/product-branches.js +52 -0
  21. package/dist/exec/register-product-message.js +50 -0
  22. package/dist/exec/register.js +22 -1
  23. package/dist/exec/repo-integration-sync.js +11 -0
  24. package/dist/exec/repo-integration.js +58 -6
  25. package/dist/exec/repo-trace.js +19 -4
  26. package/dist/exec/results.js +11 -5
  27. package/dist/exec/run/register-command.js +16 -0
  28. package/dist/exec/run/register-core.js +11 -0
  29. package/dist/exec/run/register-mode.js +19 -1
  30. package/dist/exec/run/register-resume.js +33 -1
  31. package/dist/exec/run/register-worktree.js +52 -8
  32. package/dist/exec/run/schedule-prepare.js +7 -3
  33. package/dist/exec/strategy.js +4 -1
  34. package/dist/exec/task-repos.js +92 -16
  35. package/dist/exec/worktree-command.js +2 -2
  36. package/dist/exec/worktree-ops-commit.js +7 -1
  37. package/dist/exec/worktree.js +3 -3
  38. package/dist/grade/apply.js +6 -2
  39. package/dist/grade/markdown.js +7 -2
  40. package/dist/grade/plan.js +6 -4
  41. package/dist/register/approach.js +19 -0
  42. package/dist/register/catalog-status.js +49 -0
  43. package/dist/register/core.js +8 -0
  44. package/dist/register/create-commands.js +86 -4
  45. package/dist/register/deliverable-target.js +24 -17
  46. package/dist/register/dependency.js +123 -0
  47. package/dist/register/derivation.js +2 -2
  48. package/dist/register/epic.js +42 -0
  49. package/dist/register/event-merge.js +9 -2
  50. package/dist/register/events.js +10 -0
  51. package/dist/register/external-project.js +6 -0
  52. package/dist/register/input.js +168 -0
  53. package/dist/register/item.js +71 -0
  54. package/dist/register/maintenance-commands.js +7 -1
  55. package/dist/register/planning.js +37 -0
  56. package/dist/register/register.js +7 -3
  57. package/dist/register/renumber.js +16 -4
  58. package/dist/register/update.js +6 -0
  59. package/dist/register/views.js +55 -4
  60. package/dist/schedule/approach.js +9 -0
  61. package/dist/schedule/schedule.js +3 -1
  62. package/dist/schedule/strategy-generate-scope.js +5 -1
  63. package/dist/schedule/strategy-generate.js +1 -0
  64. package/dist/schedule/strategy-profiles.js +22 -2
  65. package/dist/shared/agent-types.js +7 -1
  66. package/dist/shared/branch-template.js +26 -0
  67. package/dist/shared/commit-message-template.js +38 -0
  68. package/dist/shared/commit-types.js +15 -0
  69. package/dist/shared/grade-result.js +23 -5
  70. package/dist/shared/markdownlint-config.js +38 -0
  71. package/dist/shared/markdownlint-scaffold.js +2 -9
  72. package/dist/shared/specdojo-config.js +42 -4
  73. package/dist/shared/specdojo-gitignore.js +4 -0
  74. package/docs/ja/specdojo/exec-templates/xep-catalog-planning-template.md +24 -0
  75. package/docs/ja/specdojo/exec-templates/xep-draft-template.md +93 -0
  76. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +9 -2
  77. package/docs/ja/specdojo/exec-templates/xep-register-investigate-template.md +2 -0
  78. package/docs/ja/specdojo/exec-templates/xep-register-template.md +2 -0
  79. package/docs/ja/specdojo/exec-templates/xep-strategy-planning-template.md +24 -0
  80. package/docs/ja/specdojo/exec-templates/xer-human-bootstrap-finalize-template.md +2 -0
  81. package/docs/ja/specdojo/exec-templates/xer-human-draft-template.md +23 -0
  82. package/docs/ja/specdojo/exec-templates/xer-human-finalize-template.md +2 -0
  83. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +7 -4
  84. package/docs/ja/specdojo/guides/docs-editing-guide.md +14 -1
  85. package/docs/ja/specdojo/guides/docs-structure-guide.md +10 -8
  86. package/docs/ja/specdojo/guides/exec-config-guide.md +3 -1
  87. package/docs/ja/specdojo/guides/exec-operation-guide.md +111 -16
  88. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +19 -1
  89. package/docs/ja/specdojo/guides/practice-system-composition-guide.md +2 -0
  90. package/docs/ja/specdojo/guides/quick-start-guide.md +37 -14
  91. package/docs/ja/specdojo/guides/register-operation-guide.md +58 -16
  92. package/docs/ja/specdojo/guides/remote-host-development-guide.md +1 -1
  93. package/docs/ja/specdojo/guides/ryu-guide.md +114 -23
  94. package/docs/ja/specdojo/guides/schedule-design-guide.md +31 -4
  95. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +16 -16
  96. package/docs/ja/specdojo/guides/timeline-design-guide.md +37 -33
  97. package/docs/ja/specdojo/recipes/exec-human-finalize-recipe.md +1 -0
  98. package/docs/ja/specdojo/recipes/tsd-recipe.md +206 -0
  99. package/docs/ja/specdojo/references/command-reference.md +86 -15
  100. package/docs/ja/specdojo/references/specdojo-config-reference.md +81 -8
  101. package/docs/ja/specdojo/rulebooks/atc-index-rulebook.md +1 -0
  102. package/docs/ja/specdojo/rulebooks/atc-rulebook.md +1 -0
  103. package/docs/ja/specdojo/rulebooks/bac-rulebook.md +5 -4
  104. package/docs/ja/specdojo/rulebooks/bdd-rulebook.md +3 -2
  105. package/docs/ja/specdojo/rulebooks/bds-rulebook.md +4 -3
  106. package/docs/ja/specdojo/rulebooks/bes-index-rulebook.md +8 -7
  107. package/docs/ja/specdojo/rulebooks/bes-rulebook.md +4 -3
  108. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +1 -0
  109. package/docs/ja/specdojo/rulebooks/br-rulebook.md +1 -0
  110. package/docs/ja/specdojo/rulebooks/ccd-mermaid-rulebook.md +1 -0
  111. package/docs/ja/specdojo/rulebooks/cdfd-mermaid-rulebook.md +1 -0
  112. package/docs/ja/specdojo/rulebooks/cdfd-overview-rulebook.md +1 -0
  113. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +1 -0
  114. package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +1 -0
  115. package/docs/ja/specdojo/rulebooks/cdsd-rulebook.md +3 -2
  116. package/docs/ja/specdojo/rulebooks/cld-rulebook.md +2 -1
  117. package/docs/ja/specdojo/rulebooks/cnd-mermaid-rulebook.md +1 -0
  118. package/docs/ja/specdojo/rulebooks/cnd-rulebook.md +1 -0
  119. package/docs/ja/specdojo/rulebooks/cop-index-rulebook.md +2 -1
  120. package/docs/ja/specdojo/rulebooks/cop-rulebook.md +3 -2
  121. package/docs/ja/specdojo/rulebooks/cpd-mermaid-rulebook.md +1 -0
  122. package/docs/ja/specdojo/rulebooks/cpd-rulebook.md +1 -0
  123. package/docs/ja/specdojo/rulebooks/cstd-rulebook.md +1 -0
  124. package/docs/ja/specdojo/rulebooks/cxd-mermaid-rulebook.md +1 -0
  125. package/docs/ja/specdojo/rulebooks/cxd-rulebook.md +1 -0
  126. package/docs/ja/specdojo/rulebooks/dct-index-rulebook.md +1 -0
  127. package/docs/ja/specdojo/rulebooks/dct-rulebook.md +9 -0
  128. package/docs/ja/specdojo/rulebooks/dec-rulebook.md +1 -0
  129. package/docs/ja/specdojo/rulebooks/dmd-index-rulebook.md +2 -1
  130. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +2 -1
  131. package/docs/ja/specdojo/rulebooks/etc-index-rulebook.md +1 -0
  132. package/docs/ja/specdojo/rulebooks/etc-rulebook.md +1 -0
  133. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +9 -6
  134. package/docs/ja/specdojo/rulebooks/ifd-mermaid-rulebook.md +1 -0
  135. package/docs/ja/specdojo/rulebooks/ifx-api-rulebook.md +3 -1
  136. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +2 -1
  137. package/docs/ja/specdojo/rulebooks/ifx-file-rulebook.md +2 -1
  138. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +2 -0
  139. package/docs/ja/specdojo/rulebooks/ifx-msg-rulebook.md +4 -2
  140. package/docs/ja/specdojo/rulebooks/imp-business-rulebook.md +1 -0
  141. package/docs/ja/specdojo/rulebooks/imp-data-rulebook.md +1 -0
  142. package/docs/ja/specdojo/rulebooks/imp-interface-rulebook.md +1 -0
  143. package/docs/ja/specdojo/rulebooks/imp-operations-rulebook.md +1 -0
  144. package/docs/ja/specdojo/rulebooks/imp-test-rulebook.md +1 -0
  145. package/docs/ja/specdojo/rulebooks/itc-index-rulebook.md +1 -0
  146. package/docs/ja/specdojo/rulebooks/itc-rulebook.md +1 -0
  147. package/docs/ja/specdojo/rulebooks/mip-index-rulebook.md +2 -1
  148. package/docs/ja/specdojo/rulebooks/mm-rulebook.md +1 -0
  149. package/docs/ja/specdojo/rulebooks/mtp-rulebook.md +4 -3
  150. package/docs/ja/specdojo/rulebooks/nfr-availability-rulebook.md +9 -8
  151. package/docs/ja/specdojo/rulebooks/nfr-index-rulebook.md +10 -9
  152. package/docs/ja/specdojo/rulebooks/nfr-integrity-rulebook.md +9 -8
  153. package/docs/ja/specdojo/rulebooks/nfr-maintainability-rulebook.md +9 -8
  154. package/docs/ja/specdojo/rulebooks/nfr-operations-rulebook.md +9 -8
  155. package/docs/ja/specdojo/rulebooks/nfr-performance-rulebook.md +9 -8
  156. package/docs/ja/specdojo/rulebooks/nfr-reliability-rulebook.md +10 -9
  157. package/docs/ja/specdojo/rulebooks/nfr-security-safety-rulebook.md +9 -8
  158. package/docs/ja/specdojo/rulebooks/nfr-usability-rulebook.md +9 -8
  159. package/docs/ja/specdojo/rulebooks/ntp-rulebook.md +7 -6
  160. package/docs/ja/specdojo/rulebooks/opd-index-rulebook.md +1 -0
  161. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +1 -0
  162. package/docs/ja/specdojo/rulebooks/opr-index-rulebook.md +1 -0
  163. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +1 -0
  164. package/docs/ja/specdojo/rulebooks/otp-index-rulebook.md +2 -1
  165. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +2 -1
  166. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +54 -36
  167. package/docs/ja/specdojo/rulebooks/pm-change-request-log-rulebook.md +1 -0
  168. package/docs/ja/specdojo/rulebooks/pm-communication-plan-rulebook.md +1 -0
  169. package/docs/ja/specdojo/rulebooks/pm-issue-log-rulebook.md +1 -0
  170. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +1 -0
  171. package/docs/ja/specdojo/rulebooks/pm-organization-rulebook.md +1 -0
  172. package/docs/ja/specdojo/rulebooks/pm-plan-rulebook.md +1 -0
  173. package/docs/ja/specdojo/rulebooks/pm-quality-management-plan-rulebook.md +1 -0
  174. package/docs/ja/specdojo/rulebooks/pm-raci-rulebook.md +1 -0
  175. package/docs/ja/specdojo/rulebooks/pm-risk-register-rulebook.md +1 -0
  176. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +1 -0
  177. package/docs/ja/specdojo/rulebooks/pr-rulebook.md +1 -0
  178. package/docs/ja/specdojo/rulebooks/prj-assumptions-constraints-dependencies-rulebook.md +1 -0
  179. package/docs/ja/specdojo/rulebooks/prj-charter-rulebook.md +1 -0
  180. package/docs/ja/specdojo/rulebooks/prj-comparison-of-alternatives-rulebook.md +1 -0
  181. package/docs/ja/specdojo/rulebooks/prj-issues-and-approach-rulebook.md +1 -0
  182. package/docs/ja/specdojo/rulebooks/prj-overview-rulebook.md +1 -0
  183. package/docs/ja/specdojo/rulebooks/prj-scope-rulebook.md +1 -0
  184. package/docs/ja/specdojo/rulebooks/prj-stakeholder-register-rulebook.md +1 -0
  185. package/docs/ja/specdojo/rulebooks/prj-success-criteria-and-acceptance-criteria-rulebook.md +1 -0
  186. package/docs/ja/specdojo/rulebooks/sac-rulebook.md +3 -2
  187. package/docs/ja/specdojo/rulebooks/sch-rulebook.md +4 -1
  188. package/docs/ja/specdojo/rulebooks/sf-index-rulebook.md +7 -6
  189. package/docs/ja/specdojo/rulebooks/sf-rulebook.md +4 -3
  190. package/docs/ja/specdojo/rulebooks/sld-rulebook.md +2 -1
  191. package/docs/ja/specdojo/rulebooks/stc-index-rulebook.md +1 -0
  192. package/docs/ja/specdojo/rulebooks/stc-rulebook.md +1 -0
  193. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +1 -0
  194. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +1 -0
  195. package/docs/ja/specdojo/rulebooks/sysd-critical-flows-rulebook.md +2 -1
  196. package/docs/ja/specdojo/rulebooks/sysd-cross-cutting-policy-rulebook.md +9 -8
  197. package/docs/ja/specdojo/rulebooks/sysd-index-rulebook.md +2 -1
  198. package/docs/ja/specdojo/rulebooks/sysd-rulebook.md +1 -0
  199. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +1 -0
  200. package/docs/ja/specdojo/rulebooks/trc-requirements-to-specs-rulebook.md +1 -0
  201. package/docs/ja/specdojo/rulebooks/trc-requirements-to-tests-rulebook.md +1 -0
  202. package/docs/ja/specdojo/rulebooks/tsd-index-rulebook.md +80 -61
  203. package/docs/ja/specdojo/rulebooks/tsd-rulebook.md +111 -63
  204. package/docs/ja/specdojo/rulebooks/tsp-index-rulebook.md +1 -0
  205. package/docs/ja/specdojo/rulebooks/uis-rulebook.md +3 -2
  206. package/docs/ja/specdojo/rulebooks/utc-index-rulebook.md +1 -0
  207. package/docs/ja/specdojo/rulebooks/utc-rulebook.md +1 -0
  208. package/docs/ja/specdojo/samples/atc-index-sample.md +1 -1
  209. package/docs/ja/specdojo/samples/atc-sample.md +1 -1
  210. package/docs/ja/specdojo/samples/bac-sample.md +1 -1
  211. package/docs/ja/specdojo/samples/bdd-sample.yaml +1 -1
  212. package/docs/ja/specdojo/samples/bds-sample.md +1 -1
  213. package/docs/ja/specdojo/samples/bes-index-sample.md +1 -1
  214. package/docs/ja/specdojo/samples/bes-sample.md +1 -1
  215. package/docs/ja/specdojo/samples/ccd-sample.md +1 -1
  216. package/docs/ja/specdojo/samples/cdfd-sample.md +1 -1
  217. package/docs/ja/specdojo/samples/cdfd-uc-sample.md +1 -1
  218. package/docs/ja/specdojo/samples/cdsd-sample.md +1 -1
  219. package/docs/ja/specdojo/samples/cld-sample.md +1 -1
  220. package/docs/ja/specdojo/samples/cnd-sample.md +1 -1
  221. package/docs/ja/specdojo/samples/cop-index-sample.md +1 -1
  222. package/docs/ja/specdojo/samples/cop-sample.md +1 -1
  223. package/docs/ja/specdojo/samples/cpd-sample.md +1 -1
  224. package/docs/ja/specdojo/samples/cstd-sample.md +1 -1
  225. package/docs/ja/specdojo/samples/cxd-sample.md +1 -1
  226. package/docs/ja/specdojo/samples/dct-sample.yaml +5 -1
  227. package/docs/ja/specdojo/samples/dmd-index-sample.md +1 -1
  228. package/docs/ja/specdojo/samples/dmd-sample.md +1 -1
  229. package/docs/ja/specdojo/samples/etc-index-sample.md +1 -1
  230. package/docs/ja/specdojo/samples/etc-sample.md +1 -1
  231. package/docs/ja/specdojo/samples/gl-sample.yaml +2 -0
  232. package/docs/ja/specdojo/samples/ifd-sample.md +1 -1
  233. package/docs/ja/specdojo/samples/ifx-api-sample.yaml +1 -0
  234. package/docs/ja/specdojo/samples/ifx-cmd-sample.yaml +1 -1
  235. package/docs/ja/specdojo/samples/ifx-file-sample.md +1 -1
  236. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +1 -0
  237. package/docs/ja/specdojo/samples/ifx-msg-sample.yaml +2 -1
  238. package/docs/ja/specdojo/samples/itc-index-sample.md +1 -1
  239. package/docs/ja/specdojo/samples/itc-sample.md +1 -1
  240. package/docs/ja/specdojo/samples/mtp-sample.md +1 -1
  241. package/docs/ja/specdojo/samples/nfr-availability-sample.md +1 -1
  242. package/docs/ja/specdojo/samples/nfr-index-sample.md +1 -1
  243. package/docs/ja/specdojo/samples/nfr-integrity-sample.md +1 -1
  244. package/docs/ja/specdojo/samples/nfr-maintainability-sample.md +1 -1
  245. package/docs/ja/specdojo/samples/nfr-operations-sample.md +1 -1
  246. package/docs/ja/specdojo/samples/nfr-performance-sample.md +1 -1
  247. package/docs/ja/specdojo/samples/nfr-reliability-sample.md +1 -1
  248. package/docs/ja/specdojo/samples/nfr-security-safety-sample.md +1 -1
  249. package/docs/ja/specdojo/samples/nfr-usability-sample.md +1 -1
  250. package/docs/ja/specdojo/samples/ntp-sample.md +1 -1
  251. package/docs/ja/specdojo/samples/opd-sample.md +1 -1
  252. package/docs/ja/specdojo/samples/opr-sample.md +1 -1
  253. package/docs/ja/specdojo/samples/otp-index-sample.md +1 -1
  254. package/docs/ja/specdojo/samples/otp-sample.md +1 -1
  255. package/docs/ja/specdojo/samples/prj-stakeholder-register-sample.md +1 -1
  256. package/docs/ja/specdojo/samples/sac-sample.md +1 -1
  257. package/docs/ja/specdojo/samples/sf-index-sample.md +1 -1
  258. package/docs/ja/specdojo/samples/sf-sample.md +1 -1
  259. package/docs/ja/specdojo/samples/sld-sample.md +1 -1
  260. package/docs/ja/specdojo/samples/stc-index-sample.md +1 -1
  261. package/docs/ja/specdojo/samples/stc-sample.md +1 -1
  262. package/docs/ja/specdojo/samples/stsd-sample.md +1 -1
  263. package/docs/ja/specdojo/samples/sysd-critical-flows-sample.md +1 -1
  264. package/docs/ja/specdojo/samples/sysd-cross-cutting-policy-sample.md +1 -1
  265. package/docs/ja/specdojo/samples/sysd-index-sample.md +1 -1
  266. package/docs/ja/specdojo/samples/tsd-index-sample.md +22 -16
  267. package/docs/ja/specdojo/samples/tsd-sample.md +241 -21
  268. package/docs/ja/specdojo/samples/tsp-index-sample.md +1 -1
  269. package/docs/ja/specdojo/samples/uis-sample.md +1 -1
  270. package/docs/ja/specdojo/samples/utc-index-sample.md +1 -1
  271. package/docs/ja/specdojo/samples/utc-sample.md +1 -1
  272. package/docs/ja/specdojo/standards/document-metadata-standard.md +44 -3
  273. package/docs/ja/specdojo/standards/exec-human-finalize-standard.md +1 -0
  274. package/docs/ja/specdojo/standards/guide-authoring-standard.md +2 -1
  275. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +2 -0
  276. package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +1 -0
  277. package/docs/ja/specdojo/standards/recipe-authoring-standard.md +2 -1
  278. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +18 -12
  279. package/docs/ja/specdojo/standards/sample-authoring-standard.md +1 -0
  280. package/docs/ja/specdojo/standards/standard-authoring-standard.md +2 -1
  281. package/docs/ja/specdojo/templates/ifx-cmd-template.yaml +1 -1
  282. package/docs/ja/specdojo/templates/pjr-change-request-template.md +10 -4
  283. package/docs/ja/specdojo/templates/pjr-dependent-items-template.md +22 -0
  284. package/docs/ja/specdojo/templates/pjr-epic-items-template.md +22 -0
  285. package/docs/ja/specdojo/templates/pjr-epic-template.md +44 -0
  286. package/docs/ja/specdojo/templates/pjr-index-template.md +4 -2
  287. package/docs/ja/specdojo/templates/pjr-issue-template.md +10 -4
  288. package/docs/ja/specdojo/templates/pjr-question-template.md +11 -5
  289. package/docs/ja/specdojo/templates/pjr-risk-template.md +10 -4
  290. package/docs/ja/specdojo/templates/pjr-todo-template.md +10 -4
  291. package/docs/specdojo/schemas/v1/bdd.schema.yaml +1 -1
  292. package/docs/specdojo/schemas/v1/dct.schema.yaml +9 -0
  293. package/docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml +24 -16
  294. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +5 -1
  295. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +1 -0
  296. package/docs/specdojo/schemas/v1/exec-plan-frontmatter.schema.yaml +1 -1
  297. package/docs/specdojo/schemas/v1/gl.schema.yaml +8 -0
  298. package/docs/specdojo/schemas/v1/ifx-cmd.schema.yaml +5 -1
  299. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +2 -1
  300. package/docs/specdojo/schemas/v1/register-events.schema.yaml +21 -0
  301. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +75 -3
  302. package/docs/specdojo/schemas/v1/rulebook-frontmatter.schema.yaml +5 -0
  303. package/docs/specdojo/schemas/v1/sch-strategy.schema.yaml +1 -0
  304. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +43 -0
  305. package/package.json +4 -3
  306. package/templates/antigravity/orchestrator.md +16 -9
  307. package/templates/claude/agents/specdojo-orchestrator.md +16 -9
  308. package/templates/codex/agents/specdojo-orchestrator.toml +16 -9
  309. package/templates/codex/orchestrator.md +16 -9
  310. package/templates/copilot/README.md +2 -1
  311. package/templates/devcontainer/remote-host/specdojo-tmux.sh.sample +14 -8
  312. package/templates/opencode/agents/specdojo-orchestrator.md +16 -9
@@ -75,35 +75,39 @@ flowchart LR
75
75
 
76
76
  ### 2.4. Schedule着手可能トラックの判定
77
77
 
78
- `catalog_status: primary` のトラックを `schedule_ready_tracks` として `timeline.json` へ列挙します。これは Schedule 展開(`schedule build --track <track>`)を開始してよいトラックの一覧です。
78
+ `timeline build` は `project_register_path` がある場合、`catalog-planning` の todo を domain ごとに読み、`done` が 1 件でもあればその domain を `primary` と導出します(対象 todo がない domain は手書き値を保持)。対象ドメインがすべて `primary` に達したトラックを `schedule_ready_tracks` として `timeline.json` へ列挙します。これは Schedule 展開(`schedule build --track <track>`)を開始してよいトラックの一覧です。
79
79
 
80
80
  ## 3. 運用タイミング
81
81
 
82
- `timeline build` は一度だけ実行するコマンドではなく、`tml-index.yaml` を更新するたびに再実行する運用コマンドです。
82
+ `timeline build` は一度だけ実行するコマンドではなく、トラックの定義や register の状態変化に合わせて再実行する運用コマンドです。register の `epic` 起票から、子 todo によるカタログ・strategy 作成、Schedule への展開、完了判断までの流れは次のとおりです。
83
83
 
84
84
  ```mermaid
85
85
  flowchart TD
86
- A["人間がtml-index.yamlを更新<br/>(トラック追加・順序見直し・catalog_status変更)"] --> B["specdojo timeline build"]
87
- B --> C{"catalog-scaffold.mdに<br/>対象があるか"}
88
- C -->|"あり"| P["specdojo catalog plan prompt / scaffold --domain <domain><br/>(agent判定→dct-plan-<domain>.yaml)"]
89
- P --> D["specdojo catalog scaffold --domain <domain>"]
90
- D --> E["成果物カタログをdraft→primaryへ完成させる"]
91
- C -->|"なし"| E
92
- E --> F["tml-index.yamlのcatalog_statusをprimaryへ更新"]
93
- F --> B
94
- B --> G{"schedule_ready_tracksに<br/>該当トラックがあるか"}
95
- G -->|"あり"| H["specdojo schedule build --track <track>"]
86
+ A["人間がtml-index.yamlを定義<br/>(トラック順序・並行可否・依存関係)"] --> B["specdojo timeline build"]
87
+ B --> C["register で track の epic を起票<br/>(register add --type epic --track &lt;track&gt;)"]
88
+ C --> D["子 todo で成果物カタログを作成<br/>(approach: catalog-planning)"]
89
+ D --> E["カタログ完成後、子 todo を close<br/>(register close --id &lt;todo-id&gt;)"]
90
+ E --> F["specdojo timeline build<br/>(register から catalog_status を導出)"]
91
+ F --> G{"schedule_ready_tracks に<br/>該当トラックがあるか"}
92
+ G -->|"あり"| H["子 todo で strategy を作成<br/>(approach: strategy-planning)"]
93
+ H --> I["specdojo schedule build --track &lt;track&gt;<br/>(sch-track 生成・Schedule へ展開)"]
94
+ I --> J["schedule でタスクを実行<br/>(exec run --track / --auto)"]
95
+ J --> K["トラック完了後、epic を close<br/>(人が完了を判断)"]
96
96
  G -->|"なし"| A
97
97
  ```
98
98
 
99
99
  代表的な更新契機は次のとおりです。
100
100
 
101
- | 更新契機 | 実施すること |
102
- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------- |
103
- | 新しいトラックを追加する | `tml-index.yaml` にトラックを追加し `timeline build` を再実行する |
104
- | 成果物カタログの `draft` → `primary` 完成に伴い着手順序を確定する | `tml-index.yaml` の `catalog_status` を更新し `timeline build` を再実行する |
105
- | 着手順の見直し(並行化・順序入れ替え)が必要になる | `order` / `parallel_group` / `depends_on` を更新し `timeline build` を再実行する |
106
- | トラックの Schedule 展開前の最終確認 | `timeline build` を実行し `schedule_ready_tracks` に対象が含まれることを確認する |
101
+ | 更新契機 | 実施すること |
102
+ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
103
+ | トラックの追加・順序計画 | `tml-index.yaml` にトラックを追加・更新し `timeline build` を実行する |
104
+ | track の epic 起票 | `register add --type epic --track <track>` で業務の起点となる epic を起票する |
105
+ | 成果物カタログの計画・作成 | epic の子 todo(`--approach catalog-planning --target domain:<domain>`)で判定・生成を進め、検証後に `register close` する |
106
+ | `catalog_status` の反映と着手可能判定 | `timeline build` を再実行する(register の todo 完了から `primary` が自動導出され、`schedule_ready_tracks` に反映される) |
107
+ | トラック戦略・Schedule の生成 | epic の子 todo(`--approach strategy-planning --target track:<track>`)で strategy 生成と `schedule build --track` を行う |
108
+ | Schedule の実行と epic の完了 | schedule でタスクを実行し、途中の進み具合を確認したうえで人が epic を `register close` する |
109
+
110
+ `timeline build` は register の個票から `catalog-planning` の todo を集めて `catalog_status` を導出します。カタログ作成の todo が `done` なら `primary`、着手中(`in-progress` / `waiting` / `review`)なら `draft`、`open` だけなら `not_started` と判定します。人間が書く計画である `tml-index.yaml` の手書き値は書き換えずに保持し、手書きの値と食い違うときは警告します。
107
111
 
108
112
  ### 3.1. 既にSchedule展開済みのトラックの扱い
109
113
 
@@ -115,23 +119,23 @@ flowchart TD
115
119
 
116
120
  `catalog-scaffold.md` が示すドメインは、テンプレートに何が必要かが決まっていても、そのドメインで実際に何件の成果物インスタンスが要るかまでは決まっていません。この判定を agent に任せ、結果を機械可読な `dct-plan-<domain>.yaml` として残します。責務は次のとおり分担します。
117
121
 
118
- | 段階 | 担当 | 出力 |
119
- | ------------ | ----------------------------------- | ---------------------------------------------------------- |
120
- | 着手対象提示 | Timeline(`timeline build`) | `catalog-scaffold.md`(未作成カタログのドメイン一覧) |
121
- | 意味判断 | agent(`catalog plan`) | `dct-plan-<domain>.yaml`(インスタンス・根拠・未確定事項) |
122
- | 構造生成 | コード(`catalog scaffold --plan`) | `dct-<domain>.yaml` |
123
- | 状態更新 | 人間 | `tml-index.yaml` の `catalog_status` |
122
+ | 段階 | 担当 | 出力 |
123
+ | ------------ | ----------------------------------- | --------------------------------------------------------------------------------- |
124
+ | 着手対象提示 | Timeline(`timeline build`) | `catalog-scaffold.md`(未作成カタログのドメイン一覧) |
125
+ | 意味判断 | agent(`catalog plan`) | `dct-plan-<domain>.yaml`(インスタンス・根拠・未確定事項) |
126
+ | 構造生成 | コード(`catalog scaffold --plan`) | `dct-<domain>.yaml` |
127
+ | 状態更新 | register の todo 完了 | `timeline build` が導出する `catalog_status`(`tml-index.yaml` の値は保持・警告) |
124
128
 
125
129
  - agent は成果物インスタンスの要否、placeholder 値、採用しない候補、未確定事項の整理だけを担当します。ID・パス・`groups`・`done_criteria` の組み立てと schema 適合はコード側の責務です。
126
130
  - 判定は Timeline が着手対象として示したドメインに限定し、入力は data-flow を中心とした上流成果物と、既存カタログがある場合はその基準線に限定します。
127
- - 判定計画が保存されても `catalog_status` は自動では変わりません。`primary` への昇格は、生成された成果物カタログを人間が確認してから `tml-index.yaml` を更新します。
131
+ - 判定計画が保存されても `catalog_status` は自動では変わりません。カタログ作成の todo(`catalog-planning`)を完了(`register close`)し、`timeline build` を再実行することで `catalog_status` が `primary` と導出されます。
128
132
  - 再判定時は既存の判定計画を無条件に置き換えず、差分をレビューしてから `--force` で更新します。
129
133
  - 判定後は `catalog scaffold --plan --dry-run --domain <domain>` で差分を確認し、問題がなければ `--plan` で生成します。物理分割 domain は同じ `domain` の全 template から分割 DCT をまとめて生成します。
130
- - 生成成功だけでは `catalog_status` を変更しません。生成 DCT を人間が確認した後に `primary` へ更新し、`timeline build` を再実行します。
134
+ - 生成成功後は生成 DCT を確認・検証した後にカタログ作成の todo を close し、`timeline build` を再実行して `primary` の導出を確定します。
131
135
 
132
136
  ### 3.3. Schedule strategy 生成への引き渡し
133
137
 
134
- カタログを確認した後は、Timeline の track と `domains` が新規 strategy の scope 解決に使われます。strategy に scope と成果物別 `approach_rules` を宣言した後、`schedule strategy generate` が facts と grade から approach を導出して標準 profile へ展開します。
138
+ カタログ作成の todo を完了した後は、Timeline の track と `domains` が新規 strategy の scope 解決に使われます。epic の子 todo(`--approach strategy-planning --target track:<track>`)で strategy に scope と成果物別 `approach_rules` を宣言した後、`schedule strategy generate` が facts と grade から approach を導出して標準 profile へ展開し、`schedule build --track <track>` で Schedule を生成します。
135
139
 
136
140
  ```text
137
141
  tml-index.yaml + dct-*.yaml
@@ -152,9 +156,9 @@ tml-index.yaml + dct-*.yaml
152
156
 
153
157
  ## 5. アンチパターン
154
158
 
155
- | アンチパターン | 問題 | 対策 |
156
- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
157
- | `catalog_status` を更新しないまま成果物カタログを完成させる | `timeline build` の `schedule_ready_tracks` が実態とずれ、着手可能判定に使えない | 成果物カタログを `primary` にした時点で `tml-index.yaml` も同時に更新する |
158
- | `parallel_group` を安易に共通ラベルへ寄せる | 実際には並行させてはいけないトラックまで並行候補に見えてしまう | 並行させてよい理由が同じトラックだけを同じ `parallel_group` にする([タイムライン作成ルール](../rulebooks/tml-rulebook.md) の `order` と `parallel_group`) |
159
- | Timeline に実行実績(完了日・進捗率)を書き戻す | 計画と実績の区別がつかなくなり、`sch-milestones.yaml` と情報が二重化する | 実績は `sch-milestones.yaml` と `generated/` に任せ、Timeline は計画のみを保持する |
160
- | `timeline build` の生成物(`timeline-order.md` 等)を直接編集する | 次回 `timeline build` 実行時に上書きされ、編集内容が失われる | 変更したい内容は `tml-index.yaml` に反映してから `timeline build` を再実行する |
159
+ | アンチパターン | 問題 | 対策 |
160
+ | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
161
+ | カタログ作成の todo を close しないまま放置する | `timeline build` が `catalog_status` を `primary` と導出できず、着手可能判定が進まない | カタログ完成と検証後に `register close` で todo を完了させ、`timeline build` で最新状態を導出する |
162
+ | `parallel_group` を安易に共通ラベルへ寄せる | 実際には並行させてはいけないトラックまで並行候補に見えてしまう | 並行させてよい理由が同じトラックだけを同じ `parallel_group` にする([タイムライン作成ルール](../rulebooks/tml-rulebook.md) の `order` と `parallel_group`) |
163
+ | Timeline に実行実績(完了日・進捗率)を書き戻す | 計画と実績の区別がつかなくなり、`sch-milestones.yaml` と情報が二重化する | 実績は `sch-milestones.yaml` と `generated/` に任せ、Timeline は計画のみを保持する |
164
+ | `timeline build` の生成物(`timeline-order.md` 等)を直接編集する | 次回 `timeline build` 実行時に上書きされ、編集内容が失われる | 変更したい内容は `tml-index.yaml` に反映してから `timeline build` を再実行する |
@@ -52,6 +52,7 @@ Human Finalize Execution Recipe
52
52
  ### 4.2. 成果物の最終確認
53
53
 
54
54
  - 各 `done_criteria` について、完成版のどの記述が満たすかを確認します。
55
+ - 確定対象の本文に未反映の `_CONTEXT_:` がないことを確認します。残っていれば承認せず、元の指示と対象箇所を備考に記録して `draft` へ差し戻します。
55
56
  - 不足を直す場合は既存の責務と文脈を保ち、確定に必要な範囲だけを修正します。
56
57
  - 修正後は対象形式に対応する検証を再実行し、エラーがない状態にします。
57
58
 
@@ -0,0 +1,206 @@
1
+ ---
2
+ specdojo:
3
+ id: specdojo:tsd-recipe
4
+ type: recipe
5
+ status: draft
6
+ rulebook: specdojo:tsd-rulebook
7
+ sample: specdojo:tsd-sample
8
+ ---
9
+
10
+ # 技術領域別 技術スタック詳細定義(TSD)作成レシピ
11
+
12
+ Technology Stack Detail Definition (TSD) Writing Recipe
13
+
14
+ 採用した技術や実行基盤について、別の担当者が構成を再現し、利用できる状態か判断できる文書へ仕上げる手順を示します。初期構築、クライアント接続、日常利用の違いを整理し、設定の根拠から確認・復旧までをつなぎます。
15
+
16
+ ## 1. このレシピの使い方
17
+
18
+ - 上位設計や非機能要件から、対象の技術で実現する利用場面と守る条件を短く抜き出す。技術一覧の採用理由や組織全体の運用方針は、その正本への参照で引き継ぐ。
19
+ - 「作成前に集める情報」をメモし、「全体の作成手順」で一冊の担当範囲を決める。初期構築・接続・日常利用をまとめるか分けるかは、読み手の開始条件と設定の更新単位から判断する。
20
+ - 「各章の書き方」を使い、構成、採用値、反映操作、正常性の判定を具体化する。必要な設定例やコマンドは対象環境で再現できる粒度にし、内部クラス、詳細 API 仕様、SQL 全文の設計はその担当文書へ委ねる。
21
+ - 最後に、利用目的に対する採用設定、設定を反映する操作、確認結果の対応をたどる。文書 ID、設定項目名、確認項目名で根拠を追跡し、未実施の確認は残る作業として示す。
22
+
23
+ ## 2. 作成前に集める情報
24
+
25
+ 秘密値を収集せず、次の問いに答える短いメモを作る。確認不足は _TODO_、意思決定待ちは _UNDECIDED_、仮の前提は _ASSUMPTION_ を付け、担当と確認・判断の時期を添える。
26
+
27
+ agent に作成を任せる場合は、集めた情報や前提をどこに渡すかを決める。成果物の外から継続して渡す共通前提はカタログの `brief`、起票時や対話で決まった前提・調査選定の委任は個票の `入力`(`--input`)、成果物の特定章に対する具体的な指示は雛形内の `_CONTEXT_:` に書く。
28
+
29
+ | 入力 | 答える問い・集める情報 | 主な文脈の置き場所 |
30
+ | ------------------ | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
31
+ | 利用目的と根拠 | 誰が何をできるようにするか。上位設計のどの責務・品質条件に応えるか | カタログの `brief` または個票の `--input` |
32
+ | 文書の境界 | 技術一覧、既存の基盤定義、接続設定、利用手順のどこに正本があるか | カタログの `brief` または第 1 章(概要・位置づけ)の `_CONTEXT_:` |
33
+ | 環境と権限 | OS、実行環境、ユーザー、権限、依存の版、必要な CPU・メモリ・ディスクは何か。特別な条件がない項目はどれか | カタログの `brief`(共通基盤条件)または第 2 章(対象環境・前提条件)の `_CONTEXT_:` |
34
+ | 配置と経路 | 接続元、ホスト、コンテナ、サービスはどこで動き、どの方向へ通信するか。公開範囲はどこまでか | 第 3 章(全体構成・接続経路)の `_CONTEXT_:` または個票の `--input` |
35
+ | 設定の事実 | 導入済みの版、有効な設定、保存先、優先順位、再起動の要否を何で確認できるか | 第 5 章(導入・初期設定)の `_CONTEXT_:` または個票の `--input` |
36
+ | 採用の判断 | 決定済みの値と推奨候補は何か。互換性、ライセンス、資源の制約と採否の根拠は何か | カタログの `brief`(決定方針)または第 4 章(採用技術・設定)の `_CONTEXT_:`・`--input` |
37
+ | 認証と公開範囲 | 認証方式、秘密情報の取得・保存・参照の仕組みは何か。固有の接続先や識別子を公開できるか | 第 6 章(接続設定と秘密情報の扱い)の `_CONTEXT_:` または個票の `--input` |
38
+ | 確認と証跡 | 最小の利用成功は何か。確認場所、期待結果、確認環境・版・日付、記録先は何か | カタログの `done_criteria`(完了条件)または第 7 章(動作確認)の `_CONTEXT_:` |
39
+ | 継続利用と変更影響 | 切断、再起動、再構築で何が残るか。旧方式との競合、切り戻し、撤去で失う状態は何か | 第 8 章(継続利用・運用)・第 10 章(更新・復旧・撤去)の `_CONTEXT_:` |
40
+
41
+ ### 2.1. 文脈の置き場所の使い分けの目安
42
+
43
+ - **カタログの `brief`**: プロジェクトや成果物群で共通する技術スタック・基盤前提(例: 「静的サイト構成とし、主流の技術スタック(Astro 等)を採用する」)。YAML アンカーで複数成果物へ共有できる。
44
+ - **個票の `入力`(`--input`)**: 起票時や対話で決まった前提、または agent に技術スタックの調査や選定を任せる範囲(例: `--input "静的サイトで主流の技術スタックを調べて選定する"`)。
45
+ - **成果物内の `_CONTEXT_:`**: `deliverable scaffold --project <project-id> --target <doc-id>` で生成した雛形の各章見出し直下に書く局所的な指示(カタログにない成果物は `--target-path` と `--target-rulebook` を指定。例: 第 4 章で `_CONTEXT_: 主流のフレームワークを比較し、選定理由と採用値を提案してください`)。`draft` が本文へ反映後に削除する。
46
+
47
+ ## 3. 全体の作成手順
48
+
49
+ 1. 利用目的を一文にし、文書を読み始める人の状態と、読み終えて確認する到達状態を書き出す。独立した利用目的が混ざっていたら別文書へ分ける。
50
+ 2. 初期構築・接続設定・日常利用の担当を決める。同じ読み手が同じ前提で一続きに作業し、設定を一か所で保守できるなら一冊にまとめる。構築済み基盤を複数のクライアントが利用する、または接続・再開だけを繰り返すなら分冊を選ぶ。分冊ごとに前提の文書と開始できる確認結果をメモする。
51
+ 3. 対象が分かる `tsd-<term>.md` の名前と配置を決め、既存文書との重複を確かめる。各設定の正本を一つ決め、別冊側ではその完了条件と本書で変える差分を示す。CLI で雛形を作成する場合は `specdojo deliverable scaffold --project <project-id> --target <project-id>:tsd-<term>`(カタログにない成果物は `--target-path` と `--target-rulebook` を指定)を実行する。TSD の rulebook(`specdojo:tsd-rulebook`)は `template: not-needed` だが、`deliverable_type: architecture` を引き継いだ最小構成の雛形が生成される。
52
+ 4. 章の下書きを「概要・位置づけ」「対象環境・前提条件」「全体構成・接続経路」「採用技術・設定」「導入・初期設定」「接続設定」「動作確認」「継続利用・運用」「制約・トラブルシュート」「更新・復旧・撤去」「参照情報」の流れで置く。対象に応じて章を統合・並べ替え、扱わない手順は対象外とする理由や委譲先を概要へ残す。
53
+ 5. 接続元・ホスト・コンテナなどに呼び名を付け、配置と通信方向を図か表にする。各操作の実行場所、設定保存先、権限をこの呼び名へそろえる。
54
+ 6. 採用設定を表にし、推奨候補や任意の選択肢と分ける。実測・決定・公式情報のどれを根拠にしたか確かめ、裏付けがない版や容量は決めた値として埋めない。
55
+ 7. 導入、設定変更、接続の順序を組み立てる。設定を追加・部分変更・全体置換する範囲と、既存設定を残す方法、反映に必要な操作を各段階へ添える。
56
+ 8. 基盤の起動から最終利用まで確認を段階化し、各確認に期待結果と失敗時の戻り先を書く。設定の有効値の確認は、単なる疎通確認と分ける。
57
+ 9. 切断・再接続・再起動・再構築の違いを調べ、必要な再開操作と失われる状態を書く。移行や撤去を扱う場合は、旧方式との共存可否、切り戻し、保持するデータを先に決める。
58
+ 10. 本文、設定例、出力例を公開可否の観点で読み直す。秘密値は参照方法へ、機密の固有情報はプレースホルダーへ置き換える。
59
+ 11. 「レビュー観点」と「仕上げチェック」で、別の担当者が開始条件から正常性の判定まで進めるか確認する。未確認の条件には残る確認方法を付け、成功した事実と区別して仕上げる。
60
+
61
+ ## 4. 各章の書き方
62
+
63
+ 以下は下書きを具体化するための順序である。各章を独立させるか、関連する章へまとめるかは、読み手が行う作業に合わせて選ぶ。
64
+
65
+ ### 4.1. 概要・位置づけ
66
+
67
+ - 問い: どの利用目的に応え、初期構築・接続・日常利用のどこを扱うか。読み手が既に完了している作業は何か。
68
+ - 書き方: 目的、対象、対象外を短く置き、別冊へ進む境界にその開始条件を添える。既存文書は project 修飾 doc id の `[[id|title]]` 形式で参照し、未作成なら `tsd-<term>.md` のような仮のファイル名で示す。
69
+ - 良い例: 「構築済み基盤へ接続するクライアントの設定を扱う。基盤側の起動と利用対象の登録確認を開始条件とし、本体の導入は基盤定義へ委ねる」。避けたい例: 「関連技術の設定をまとめる」だけで責務を決めない。
70
+
71
+ ### 4.2. 対象環境・前提条件
72
+
73
+ - 問い: コマンドをどこで、誰が、どの shell・作業ディレクトリで実行するか。OS や版によって変わる条件はあるか。
74
+ - 書き方: 実行場所ごとに OS、ランタイム、権限、導入済みの依存、必要資源をそろえる。特別な権限や追加資源が不要なら、その旨を明記する。実測した環境と一般的な推奨環境を分ける。
75
+ - 良い例: 「ホストで常駐プロセスを管理し、接続元コンテナで利用確認する。管理者権限を使う操作は導入時だけ」。避けたい例: 「ローカルで実行する」とだけ書き、端末とホストを混同させる。
76
+
77
+ ### 4.3. 全体構成・接続経路
78
+
79
+ - 問い: どのプロセスがどこで動き、どこからどこへ接続するか。待受アドレス、接続先アドレス、公開範囲は対応するか。
80
+ - 書き方: 配置と通信方向を図か対応表にし、端末・ホスト・コンテナの境界を先に描く。名前解決、ポート転送、トンネルを使う場合は、経路ごとに入口と出口を結ぶ。
81
+ - 良い例: 「接続元 → トンネル → ホストの公開ポート → コンテナの待受ポート」と経路を示す。避けたい例: すべてを同じ `localhost` とし、どの環境のアドレスか説明しない。
82
+
83
+ ### 4.4. 採用技術・設定
84
+
85
+ - 問い: その値は何を満たすために採用したか。候補・任意設定・未決事項との違いは何か。設定ファイルと環境変数のどちらが実行プロセスへ反映されるか。
86
+ - 書き方: 次の表へ、設定の適用範囲と確認方法まで一行でつなぐ。GUI 設定も画面項目・保存先・反映条件を調べる。推奨値を適用する場合は、採用を決めた記録を別に残す。
87
+ - 良い例: 「推奨候補の並列数は評価後に採否を決める。現行の採用値は有効値の確認結果に基づく」。避けたい例: 推奨値を無条件に採用済みの表へ混ぜる。
88
+
89
+ | 対象・用途 | 設定項目 | 採用値・版 | 適用範囲 | 理由・制約 | 反映・確認方法 |
90
+ | ------------------ | -------------- | -------------------- | ------------------------ | -------------- | ------------------------------ |
91
+ | 利用場面と構成要素 | 製品上の項目名 | 決定した値・単位・版 | 環境・ユーザー・プロセス | 根拠と適用条件 | 保存先・反映操作・有効値の確認 |
92
+
93
+ 下書きでは次のように状態を整理し、未決の値を採用値の代わりに埋めない。
94
+
95
+ | 状態 | 書き進める方法 |
96
+ | ------------ | ---------------------------------------------------------------------- |
97
+ | 採用値 | 決定の根拠と対象環境を示し、反映操作と確認へつなぐ |
98
+ | 推奨値 | 推奨する条件と採否の判断方法を添え、現行の採用値と分ける |
99
+ | 任意の選択肢 | 利用する場合の前提と追加確認を示し、共通手順から分岐させる |
100
+ | 確認不足 | _TODO_: 確認対象・方法・担当・確認時期を記す |
101
+ | 意思決定待ち | _UNDECIDED_: 選択肢・判断基準・担当・判断期限・未決による影響を記す |
102
+ | 仮の前提 | _ASSUMPTION_: 仮置きの根拠・成立条件・検証方法・担当・見直し時期を記す |
103
+
104
+ ### 4.5. 導入・初期設定
105
+
106
+ - 問い: 何を先に導入し、どの保存先を変更するか。既存の利用者設定を残せるか。再起動や権限変更で何が影響を受けるか。
107
+ - 書き方: 順序付き手順に実行場所、shell、作業ディレクトリ、事前条件、変更先を付ける。コマンドや再現に必要な補助スクリプトは言語識別子付きコードブロックへ置き、追加・部分変更・全体置換を区別する。導入と起動、起動と再起動は別の段階にする。
108
+ - 良い例: 「既存設定の対象セクションへ追加し、他の接続先を保持する。反映前にバックアップを取り、再起動が既存セッションへ与える影響を確認する」。避けたい例: ファイル全体の例を示して、そのまま上書きさせる。
109
+
110
+ ### 4.6. 接続設定と秘密情報の扱い
111
+
112
+ - 問い: 接続方式と認証方式は何か。接続先の登録名、クライアントの選択名、リクエスト中の識別子は対応するか。例に含める値を公開できるか。
113
+ - 書き方: 接続先の基点、認証情報の参照方法、識別子の対応を先に整理する。秘密値を読まずに、設定の仕組みと公開可否を判断し、次の順序で例を作る。
114
+ - 良い例: 汎用の接続先 `service.example.invalid` と `<TOKEN>` を説明用に置き、実行時は credential store から渡す方法を示す。避けたい例: 実トークン付き URL や認証設定の全文を貼る。
115
+
116
+ 1. ポートや接続方式、汎用ホスト名など、再現に必要で公開できる情報を選ぶ。接続情報という理由だけで一律に隠さない。
117
+ 2. 個人・組織固有のホスト名、アカウント、URL は公開可否を確かめ、機密なら `<SERVICE_HOST>` などのプレースホルダーへ置き換える。公開可否が不明なら _TODO_ として確認先を示す。
118
+ 3. API キー、トークン、パスワード、秘密鍵は実値を載せず、取得・保存・注入・参照方法を書く。認証不要の方式なら、その適用範囲と公開範囲を説明する。
119
+ 4. 設定例、URL、出力例、ログ例、コマンド履歴にも秘密が残らない形を選ぶ。公開用の例と実行時に供給する値の対応を説明する。
120
+
121
+ ### 4.7. 動作確認
122
+
123
+ - 問い: 起動、疎通、認証、識別子の解決、実際の利用のうち何を確認できたか。失敗したら一つ前のどの前提へ戻るか。
124
+ - 書き方: 下の段階を対象に合わせて選び、確認対象、実行場所・方法、期待結果、失敗時の確認先を表にする。認証不要などの段階は理由を添えて省く。有効値や版は専用の表示・照会で確かめ、疎通成功だけから設定反映を推定しない。
125
+ - 良い例: 「一覧応答は疎通と登録済み識別子の確認に使い、最小入力への応答で利用機能を確かめる」。避けたい例: 「起動したので設定と接続はすべて正常」とする。
126
+
127
+ | 段階 | 確認の組み立て方 | 期待結果と切り分けの例 |
128
+ | -------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------ |
129
+ | 基盤・プロセス | 基盤側で依存と起動状態、必要な有効値を確認する | 対象プロセスが稼働し、有効値が採用値に一致する。起動設定・反映操作・ログへ戻る |
130
+ | 名前解決・疎通 | 実際の接続元から対象の入口へ到達できるか確認する | 接続でき、所定の応答項目が返る。名前解決・待受・転送・公開範囲を調べる |
131
+ | 認証・識別子 | 認証方式と利用対象の登録名・選択名を確認する | 対象の権限と識別子で利用できる。認証の参照先・権限・登録名の対応へ戻る |
132
+ | 最小利用 | 小さい入力で一機能を実行し、クライアント経由でも確認する | 意図した結果が得られる。直接利用が成功するならクライアント固有設定を調べる |
133
+
134
+ 負荷や応答時間の目標を扱うなら、根拠となる要求とともに入力サイズ、並列数、初回・再実行の別、測定方法、合否を判断する時点をそろえる。未実施なら _TODO_ と確認環境・担当・残る方法を残し、想定する期待結果と実測した結果を分ける。
135
+
136
+ ### 4.8. 継続利用・運用
137
+
138
+ - 問い: 切断後に戻る場所はどこか。再接続だけで再開するものと、明示的な再開が必要なものは何か。設定、認証状態、作業データ、実行中セッションはどこに保存されるか。
139
+ - 書き方: 通信切断、プロセス再起動、環境再構築を分け、保持する状態と復元操作を表にする。長時間実行は監視対象、根拠のある正常範囲、負荷を減らす判断条件を添える。組織的な監視体制やバックアップ方針は運用設計へ委ねる。
140
+ - 良い例: 「接続断では実行セッションへ戻り、プロセス終了時は明示的に再開する。再構築時は永続化した設定を復元し、失ったセッションを作り直す」。避けたい例: 「接続し直せばすべて再開する」。
141
+
142
+ ### 4.9. 制約・トラブルシュート
143
+
144
+ - 問い: どの症状からどの段階の失敗を疑うか。確認済みの制約と未検証の条件はどれか。
145
+ - 書き方: 動作確認の失敗先を症状別に並べ、最初の確認、次の確認、回避・復旧を結ぶ。原因が確定していないものは仮説として扱い、設定の削除や再インストールより先に観測できる情報を選ぶ。
146
+ - 良い例: 「基盤からの応答はあるがクライアントで対象を選べない場合、登録識別子と選択名を照合する」。避けたい例: 「接続できなければ再インストール」。
147
+
148
+ ### 4.10. 更新・復旧・撤去
149
+
150
+ - 問い: 旧方式と共存できるか。何を停止し、何を保存してから変更するか。どの確認で切り戻しを判断するか。
151
+ - 書き方: 競合する待受・自動起動・保存先を洗い出し、変更前の退避、旧方式の停止、新方式への変更、確認、切り戻しの順に書く。撤去はプロセス、設定、認証状態、データごとに保持・削除を分ける。
152
+ - 良い例: 「新方式の利用確認が失敗したら旧設定へ戻す。データ削除は撤去とは別の選択として影響と復元可否を示す」。避けたい例: 停止や再構築の手順にデータ削除を混ぜる。
153
+
154
+ ### 4.11. 参照情報
155
+
156
+ - 問い: 採用判断や手順のどの主張を、どの資料・確認記録で確かめ直せるか。適用した版や確認日は分かるか。
157
+ - 書き方: 公式情報には対象の版や確認日、関連文書にはその責務を添える。設定表や確認項目から根拠へたどれる名前を使い、参考に読んだ資料をすべて採用根拠にしない。
158
+ - 良い例: 「環境変数の反映条件」の根拠を、適用した版の公式情報と確認記録へ結ぶ。避けたい例: 製品トップページだけを列挙し、何を裏付けるか示さない。
159
+
160
+ ## 5. 深掘り手順
161
+
162
+ 1. 主要な採用設定を一つ選び、利用目的や上位の品質条件へ戻れるか調べる。戻れなければ、値の追加より先に採用理由を明らかにする。
163
+ 2. 設定ごとに保存先、適用範囲、優先順位、反映操作、有効値の確認をつなぐ。shell で見える値と常駐プロセスが受け取る値が同じか確かめる。
164
+ 3. 接続元を起点に経路をたどり、基盤側で成功する確認とクライアント側で成功する確認を分ける。識別子は登録・選択・確認要求の三か所で照合する。
165
+ 4. 再接続や再構築を仮に起こしたとして、保存された設定だけで復帰できるか点検する。セッションや一時データが足りなければ再開操作を具体化する。
166
+ 5. 事実に見える未検証の主張を探し、確認不足・意思決定待ち・仮の前提へ分ける。それぞれに確認・判断方法と担当、時期を付ける。
167
+ 6. 別冊と同じ設定値を持つ箇所を探し、正本を一つに寄せる。参照側には値の転載に代えて開始条件と本書で変える差分を残す。
168
+
169
+ ## 6. 良い例 / 悪い例
170
+
171
+ | 観点 | 良い例 | 悪い例 |
172
+ | ---------------- | ------------------------------------------------------------ | --------------------------------------------------- |
173
+ | 文書の分け方 | 基盤導入と接続を分け、接続側に基盤の完了確認と差分だけを書く | 分冊した双方へ同じ導入・設定を転載する |
174
+ | 実行場所 | ホストで起動し、接続元コンテナから疎通を確認する | 「端末で実行する」だけで場所を特定しない |
175
+ | 値の根拠 | 現行の採用値と推奨候補を分け、未決には判断条件を付ける | 手本の版・容量・並列数をそのまま必須にする |
176
+ | 設定の反映 | 保存先と優先順位を示し、反映後に対象プロセスの有効値を調べる | shell の値や API の応答だけで全設定の反映を断定する |
177
+ | 既存設定との統合 | 既存の接続先を保持して対象項目を追加する | 設定例で既存ファイル全体を無条件に置換する |
178
+ | 確認の段階 | 疎通、認証、識別子、最小利用を分け、失敗時に戻る箇所を示す | クライアントを起動できれば利用可能とする |
179
+ | 継続利用 | 切断後の再接続と処理の再開を区別する | 履歴が保存されれば進行中の処理も自動再開するとする |
180
+ | 秘密情報 | 公開可能な経路を示し、秘密値は保存・参照方法で説明する | 認証設定やログの全文を実値のまま貼る |
181
+ | 撤去 | 自動起動・本体・設定・データの扱いと復元可否を分ける | アンインストールに全データ削除を含める |
182
+
183
+ ## 7. レビュー観点
184
+
185
+ | 観点 | 確認内容 |
186
+ | ------------ | ---------------------------------------------------------------------------------------- |
187
+ | 目的との対応 | 主要な設定が利用目的・品質条件に結び付き、採用理由と制約を説明できるか |
188
+ | 文書の境界 | 一冊の開始・完了状態が分かり、分冊した設定の正本と差分をたどれるか |
189
+ | 環境と再現性 | OS・版・権限・依存・資源、実行場所・shell・変更先を特定できるか |
190
+ | 判断の確度 | 採用・推奨・任意・未決・仮説が混ざらず、未確定事項の担当と確認・判断時期が分かるか |
191
+ | 反映と検証 | 採用値から反映操作・有効値・最終利用までを確認でき、失敗時の戻り先が分かるか |
192
+ | 継続性と復旧 | 切断・再起動・再構築で保持・喪失する状態と、再開・切り戻し操作が対応するか |
193
+ | 公開適性 | 接続経路の説明を残しつつ、秘密値や機密の固有情報を本文・設定例・出力例から除けているか |
194
+ | 委譲と追跡 | 詳細 API・内部設計・組織的な運用方針を担当文書へ委ね、採用判断と確認の根拠を追跡できるか |
195
+
196
+ ## 8. 仕上げチェック
197
+
198
+ - 初期構築・接続設定・日常利用の担当範囲と対象外が分かり、別冊の手順を始める条件が具体化されている。
199
+ - 構成の呼び名と各操作の実行場所が一致し、接続元から利用先までの経路と公開範囲をたどれる。
200
+ - 採用値に根拠と適用範囲があり、推奨値や任意設定、未決事項を採用済みと誤読しない。
201
+ - 設定の保存先、優先順位、反映条件がつながり、既存設定を保持する方法と変更影響が分かる。
202
+ - 確認に期待結果と失敗時の確認先があり、疎通と設定反映、最小利用を別々に判定できる。未実施の確認を成功としていない。
203
+ - 継続利用や変更を扱う箇所には、状態の保存、再開、切り戻し、削除の影響が対応している。
204
+ - 秘密値を含めず、機密情報のプレースホルダーと実行時の取得・参照方法が対応している。
205
+ - 参照先の存在、表内の wikilink の区切りのエスケープ、見出し名による章参照を確かめた。未作成の文書はコード表記で仮置きしている。
206
+ - 確認不足・未決・仮の前提には担当と確認・判断の時期があり、判断や再現を妨げる点を読み手が識別できる。