specdojo 0.8.0 → 0.9.1

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 (292) hide show
  1. package/.github/agents/specdojo-orchestrator.md +4 -1
  2. package/CHANGELOG.md +77 -0
  3. package/dist/catalog/catalog.js +16 -14
  4. package/dist/commands/agent.js +5 -3
  5. package/dist/commands/build.js +69 -10
  6. package/dist/commands/git.js +206 -0
  7. package/dist/commands/init.js +4 -2
  8. package/dist/commands/orchestrator.js +5 -77
  9. package/dist/commands/where.js +25 -0
  10. package/dist/dashboard/dashboard.js +5 -3
  11. package/dist/dashboard/routines.js +4 -7
  12. package/dist/dashboard/shared.js +2 -2
  13. package/dist/dashboard/timeline.js +14 -14
  14. package/dist/deliverable/trash.js +2 -1
  15. package/dist/docs/index-command.js +2 -2
  16. package/dist/docs/yaml-business-tables.js +243 -0
  17. package/dist/docs/yaml-interface-tables.js +106 -0
  18. package/dist/docs/yaml-pages-command.js +5 -3
  19. package/dist/docs/yaml-pages.js +146 -3
  20. package/dist/docs/yaml-table-shared.js +70 -0
  21. package/dist/docs/yaml-tables.js +39 -0
  22. package/dist/exec/agent-config.js +9 -0
  23. package/dist/exec/agent-protected-config.js +2 -0
  24. package/dist/exec/commands.js +31 -18
  25. package/dist/exec/events.js +34 -14
  26. package/dist/exec/evidence.js +13 -3
  27. package/dist/exec/opencode-permissions.js +117 -0
  28. package/dist/exec/parent-validation.js +56 -3
  29. package/dist/exec/plans-core.js +21 -2
  30. package/dist/exec/plans-generation.js +6 -7
  31. package/dist/exec/post-integration.js +162 -0
  32. package/dist/exec/queue-command.js +166 -0
  33. package/dist/exec/queue.js +285 -0
  34. package/dist/exec/register-foreign-wait.js +82 -0
  35. package/dist/exec/repo-integration-sync.js +17 -5
  36. package/dist/exec/repo-trace.js +2 -1
  37. package/dist/exec/reporter.js +2 -2
  38. package/dist/exec/results.js +24 -4
  39. package/dist/exec/review-kata.js +4 -1
  40. package/dist/exec/run/agent-pipeline.js +3 -2
  41. package/dist/exec/run/agent.js +12 -6
  42. package/dist/exec/run/change-scope.js +365 -0
  43. package/dist/exec/run/deferred-cleanup.js +31 -0
  44. package/dist/exec/run/in-place.js +5 -2
  45. package/dist/exec/run/job-lock.js +66 -0
  46. package/dist/exec/run/job-sequence.js +137 -0
  47. package/dist/exec/run/job.js +56 -19
  48. package/dist/exec/run/lifecycle-commands.js +1 -1
  49. package/dist/exec/run/lock.js +22 -1
  50. package/dist/exec/run/register-command.js +8 -5
  51. package/dist/exec/run/register-mode.js +68 -8
  52. package/dist/exec/run/register-resume.js +68 -14
  53. package/dist/exec/run/register-state.js +13 -8
  54. package/dist/exec/run/register-worktree.js +140 -125
  55. package/dist/exec/run/schedule-mode.js +75 -14
  56. package/dist/exec/run/schedule-prepare.js +3 -0
  57. package/dist/exec/run/schedule-task.js +88 -38
  58. package/dist/exec/run/shared.js +5 -0
  59. package/dist/exec/schedule/schedule.js +116 -4
  60. package/dist/exec/shared.js +2 -2
  61. package/dist/exec/smoke.js +190 -0
  62. package/dist/exec/strategy.js +13 -3
  63. package/dist/exec/task-repos.js +19 -4
  64. package/dist/exec/task-view.js +6 -4
  65. package/dist/exec/trial-commands.js +5 -2
  66. package/dist/exec/trial-core.js +6 -1
  67. package/dist/exec/validation-metrics.js +181 -0
  68. package/dist/exec/worktree-cleanup-lock.js +26 -0
  69. package/dist/exec/worktree-command.js +12 -2
  70. package/dist/exec/worktree-ops-commit.js +2 -2
  71. package/dist/exec/worktree.js +13 -2
  72. package/dist/grade/command-apply.js +3 -3
  73. package/dist/grade/command-inspect.js +5 -3
  74. package/dist/grade/command-plan.js +1 -1
  75. package/dist/grade/command-run.js +5 -1
  76. package/dist/grade/run.js +64 -8
  77. package/dist/job/definition.js +84 -8
  78. package/dist/job/job.js +79 -23
  79. package/dist/register/authoring-sources.js +22 -16
  80. package/dist/register/maintenance-commands.js +2 -2
  81. package/dist/register/register.js +31 -7
  82. package/dist/register/renumber.js +1 -3
  83. package/dist/routine/definition.js +9 -0
  84. package/dist/routine/routine.js +137 -43
  85. package/dist/routine/status.js +62 -0
  86. package/dist/schedule/schedule.js +38 -39
  87. package/dist/shared/agent-types.js +5 -0
  88. package/dist/shared/cross-process-lock.js +9 -1
  89. package/dist/shared/dist-freshness.js +8 -2
  90. package/dist/shared/git-environment.js +2 -1
  91. package/dist/shared/git.js +44 -1
  92. package/dist/shared/lefthook-scaffold.js +3 -0
  93. package/dist/shared/local-config.js +244 -0
  94. package/dist/shared/specdojo-config.js +34 -20
  95. package/dist/shared/specdojo-gitignore.js +1 -0
  96. package/dist/shared/text.js +17 -1
  97. package/dist/shared/where-alias.js +13 -0
  98. package/dist/specdojo.js +4 -0
  99. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +2 -0
  100. package/docs/ja/specdojo/guides/exec-config-guide.md +23 -4
  101. package/docs/ja/specdojo/guides/exec-operation-guide.md +44 -1
  102. package/docs/ja/specdojo/guides/job-sequence-guide.md +77 -0
  103. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +1 -1
  104. package/docs/ja/specdojo/guides/quick-start-guide.md +3 -3
  105. package/docs/ja/specdojo/guides/register-operation-guide.md +1 -1
  106. package/docs/ja/specdojo/guides/routine-operation-guide.md +11 -6
  107. package/docs/ja/specdojo/guides/schedule-design-guide.md +20 -17
  108. package/docs/ja/specdojo/guides/waza-guide.md +12 -8
  109. package/docs/ja/specdojo/recipes/bac-recipe.md +66 -49
  110. package/docs/ja/specdojo/recipes/bes-recipe.md +90 -54
  111. package/docs/ja/specdojo/recipes/bps-recipe.md +88 -139
  112. package/docs/ja/specdojo/recipes/br-recipe.md +40 -47
  113. package/docs/ja/specdojo/recipes/cdfd-overview-recipe.md +97 -109
  114. package/docs/ja/specdojo/recipes/cdfd-recipe.md +85 -146
  115. package/docs/ja/specdojo/recipes/cdfd-uc-recipe.md +91 -110
  116. package/docs/ja/specdojo/recipes/cnd-recipe.md +79 -69
  117. package/docs/ja/specdojo/recipes/cpd-recipe.md +78 -64
  118. package/docs/ja/specdojo/recipes/cxd-recipe.md +92 -75
  119. package/docs/ja/specdojo/recipes/ifd-recipe.md +79 -68
  120. package/docs/ja/specdojo/recipes/ifx-cmd-recipe.md +78 -105
  121. package/docs/ja/specdojo/recipes/ifx-index-recipe.md +105 -71
  122. package/docs/ja/specdojo/recipes/pm-communication-plan-recipe.md +60 -49
  123. package/docs/ja/specdojo/recipes/pm-members-recipe.md +50 -51
  124. package/docs/ja/specdojo/recipes/pm-organization-recipe.md +59 -51
  125. package/docs/ja/specdojo/recipes/pm-plan-recipe.md +69 -56
  126. package/docs/ja/specdojo/recipes/pm-quality-management-plan-recipe.md +37 -56
  127. package/docs/ja/specdojo/recipes/pm-raci-recipe.md +39 -53
  128. package/docs/ja/specdojo/recipes/pm-roles-recipe.md +52 -79
  129. package/docs/ja/specdojo/recipes/prj-assumptions-constraints-dependencies-recipe.md +64 -93
  130. package/docs/ja/specdojo/recipes/prj-charter-recipe.md +71 -106
  131. package/docs/ja/specdojo/recipes/prj-comparison-of-alternatives-recipe.md +78 -157
  132. package/docs/ja/specdojo/recipes/prj-issues-and-approach-recipe.md +62 -111
  133. package/docs/ja/specdojo/recipes/prj-scope-recipe.md +67 -123
  134. package/docs/ja/specdojo/recipes/prj-stakeholder-register-recipe.md +60 -96
  135. package/docs/ja/specdojo/recipes/prj-success-criteria-and-acceptance-criteria-recipe.md +61 -105
  136. package/docs/ja/specdojo/recipes/stsd-recipe.md +79 -109
  137. package/docs/ja/specdojo/recipes/sysd-critical-flows-recipe.md +78 -55
  138. package/docs/ja/specdojo/recipes/sysd-cross-cutting-policy-recipe.md +82 -73
  139. package/docs/ja/specdojo/recipes/sysd-index-recipe.md +78 -59
  140. package/docs/ja/specdojo/recipes/tsd-recipe.md +149 -129
  141. package/docs/ja/specdojo/references/command-reference.md +258 -118
  142. package/docs/ja/specdojo/references/deliverables-reference.md +21 -12
  143. package/docs/ja/specdojo/references/specdojo-config-reference.md +47 -10
  144. package/docs/ja/specdojo/rulebooks/atc-index-rulebook.md +101 -257
  145. package/docs/ja/specdojo/rulebooks/atc-rulebook.md +102 -228
  146. package/docs/ja/specdojo/rulebooks/bac-rulebook.md +19 -28
  147. package/docs/ja/specdojo/rulebooks/bdd-rulebook.md +16 -67
  148. package/docs/ja/specdojo/rulebooks/bds-rulebook.md +30 -51
  149. package/docs/ja/specdojo/rulebooks/bes-index-rulebook.md +41 -61
  150. package/docs/ja/specdojo/rulebooks/bes-rulebook.md +22 -50
  151. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +24 -56
  152. package/docs/ja/specdojo/rulebooks/br-rulebook.md +13 -38
  153. package/docs/ja/specdojo/rulebooks/ccd-mermaid-rulebook.md +41 -76
  154. package/docs/ja/specdojo/rulebooks/cdfd-d2-rulebook.md +18 -93
  155. package/docs/ja/specdojo/rulebooks/cdfd-mermaid-rulebook.md +18 -52
  156. package/docs/ja/specdojo/rulebooks/cdfd-overview-rulebook.md +109 -147
  157. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +80 -108
  158. package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +21 -46
  159. package/docs/ja/specdojo/rulebooks/cdr-rulebook.md +144 -0
  160. package/docs/ja/specdojo/rulebooks/cdsd-rulebook.md +27 -48
  161. package/docs/ja/specdojo/rulebooks/cdt-rulebook.md +37 -50
  162. package/docs/ja/specdojo/rulebooks/clis-rulebook.md +52 -69
  163. package/docs/ja/specdojo/rulebooks/cnd-mermaid-rulebook.md +33 -86
  164. package/docs/ja/specdojo/rulebooks/cnd-rulebook.md +16 -32
  165. package/docs/ja/specdojo/rulebooks/cop-index-rulebook.md +45 -131
  166. package/docs/ja/specdojo/rulebooks/cop-rulebook.md +69 -275
  167. package/docs/ja/specdojo/rulebooks/cpd-mermaid-rulebook.md +20 -112
  168. package/docs/ja/specdojo/rulebooks/cpd-rulebook.md +23 -56
  169. package/docs/ja/specdojo/rulebooks/cxd-mermaid-rulebook.md +12 -145
  170. package/docs/ja/specdojo/rulebooks/cxd-rulebook.md +39 -47
  171. package/docs/ja/specdojo/rulebooks/dct-index-rulebook.md +37 -56
  172. package/docs/ja/specdojo/rulebooks/dct-rulebook.md +118 -175
  173. package/docs/ja/specdojo/rulebooks/dec-rulebook.md +5 -14
  174. package/docs/ja/specdojo/rulebooks/dmd-index-rulebook.md +22 -66
  175. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +36 -94
  176. package/docs/ja/specdojo/rulebooks/dss-rulebook.md +59 -81
  177. package/docs/ja/specdojo/rulebooks/etc-index-rulebook.md +31 -131
  178. package/docs/ja/specdojo/rulebooks/etc-rulebook.md +50 -104
  179. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +51 -61
  180. package/docs/ja/specdojo/rulebooks/ifd-mermaid-rulebook.md +38 -45
  181. package/docs/ja/specdojo/rulebooks/ifx-api-rulebook.md +14 -20
  182. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +26 -38
  183. package/docs/ja/specdojo/rulebooks/ifx-file-rulebook.md +26 -107
  184. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +42 -49
  185. package/docs/ja/specdojo/rulebooks/ifx-msg-rulebook.md +14 -22
  186. package/docs/ja/specdojo/rulebooks/imp-business-rulebook.md +21 -44
  187. package/docs/ja/specdojo/rulebooks/imp-data-rulebook.md +41 -64
  188. package/docs/ja/specdojo/rulebooks/imp-interface-rulebook.md +14 -38
  189. package/docs/ja/specdojo/rulebooks/imp-operations-rulebook.md +34 -61
  190. package/docs/ja/specdojo/rulebooks/imp-test-rulebook.md +27 -50
  191. package/docs/ja/specdojo/rulebooks/itc-index-rulebook.md +70 -199
  192. package/docs/ja/specdojo/rulebooks/itc-rulebook.md +65 -153
  193. package/docs/ja/specdojo/rulebooks/mip-index-rulebook.md +74 -150
  194. package/docs/ja/specdojo/rulebooks/mm-rulebook.md +11 -23
  195. package/docs/ja/specdojo/rulebooks/mtp-rulebook.md +99 -176
  196. package/docs/ja/specdojo/rulebooks/nfr-availability-rulebook.md +35 -61
  197. package/docs/ja/specdojo/rulebooks/nfr-index-rulebook.md +75 -117
  198. package/docs/ja/specdojo/rulebooks/nfr-integrity-rulebook.md +31 -60
  199. package/docs/ja/specdojo/rulebooks/nfr-maintainability-rulebook.md +26 -81
  200. package/docs/ja/specdojo/rulebooks/nfr-operations-rulebook.md +32 -70
  201. package/docs/ja/specdojo/rulebooks/nfr-performance-rulebook.md +45 -87
  202. package/docs/ja/specdojo/rulebooks/nfr-reliability-rulebook.md +48 -101
  203. package/docs/ja/specdojo/rulebooks/nfr-security-safety-rulebook.md +44 -80
  204. package/docs/ja/specdojo/rulebooks/nfr-usability-rulebook.md +59 -127
  205. package/docs/ja/specdojo/rulebooks/opd-index-rulebook.md +31 -50
  206. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +42 -109
  207. package/docs/ja/specdojo/rulebooks/opr-index-rulebook.md +29 -42
  208. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +29 -87
  209. package/docs/ja/specdojo/rulebooks/otp-index-rulebook.md +62 -84
  210. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +11 -61
  211. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +91 -106
  212. package/docs/ja/specdojo/rulebooks/pm-change-request-log-rulebook.md +25 -34
  213. package/docs/ja/specdojo/rulebooks/pm-communication-plan-rulebook.md +30 -53
  214. package/docs/ja/specdojo/rulebooks/pm-issue-log-rulebook.md +23 -35
  215. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +27 -45
  216. package/docs/ja/specdojo/rulebooks/pm-organization-rulebook.md +37 -45
  217. package/docs/ja/specdojo/rulebooks/pm-plan-rulebook.md +45 -46
  218. package/docs/ja/specdojo/rulebooks/pm-quality-management-plan-rulebook.md +37 -48
  219. package/docs/ja/specdojo/rulebooks/pm-raci-rulebook.md +25 -29
  220. package/docs/ja/specdojo/rulebooks/pm-risk-register-rulebook.md +28 -35
  221. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +36 -41
  222. package/docs/ja/specdojo/rulebooks/pr-rulebook.md +5 -18
  223. package/docs/ja/specdojo/rulebooks/prj-assumptions-constraints-dependencies-rulebook.md +16 -37
  224. package/docs/ja/specdojo/rulebooks/prj-charter-rulebook.md +23 -97
  225. package/docs/ja/specdojo/rulebooks/prj-comparison-of-alternatives-rulebook.md +39 -57
  226. package/docs/ja/specdojo/rulebooks/prj-issues-and-approach-rulebook.md +43 -116
  227. package/docs/ja/specdojo/rulebooks/prj-scope-rulebook.md +16 -51
  228. package/docs/ja/specdojo/rulebooks/prj-stakeholder-register-rulebook.md +47 -92
  229. package/docs/ja/specdojo/rulebooks/prj-success-criteria-and-acceptance-criteria-rulebook.md +25 -84
  230. package/docs/ja/specdojo/rulebooks/sac-rulebook.md +44 -107
  231. package/docs/ja/specdojo/rulebooks/sf-index-rulebook.md +39 -49
  232. package/docs/ja/specdojo/rulebooks/sf-rulebook.md +42 -49
  233. package/docs/ja/specdojo/rulebooks/sld-rulebook.md +64 -89
  234. package/docs/ja/specdojo/rulebooks/stc-index-rulebook.md +90 -189
  235. package/docs/ja/specdojo/rulebooks/stc-rulebook.md +45 -105
  236. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +6 -12
  237. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +49 -68
  238. package/docs/ja/specdojo/rulebooks/sysd-critical-flows-rulebook.md +51 -60
  239. package/docs/ja/specdojo/rulebooks/sysd-cross-cutting-policy-rulebook.md +46 -50
  240. package/docs/ja/specdojo/rulebooks/sysd-index-rulebook.md +39 -64
  241. package/docs/ja/specdojo/rulebooks/sysd-rulebook.md +47 -60
  242. package/docs/ja/specdojo/rulebooks/trc-requirements-to-specs-rulebook.md +69 -70
  243. package/docs/ja/specdojo/rulebooks/trc-requirements-to-tests-rulebook.md +65 -72
  244. package/docs/ja/specdojo/rulebooks/tsd-index-rulebook.md +35 -46
  245. package/docs/ja/specdojo/rulebooks/tsd-rulebook.md +49 -66
  246. package/docs/ja/specdojo/rulebooks/tsp-index-rulebook.md +64 -139
  247. package/docs/ja/specdojo/rulebooks/uis-rulebook.md +41 -108
  248. package/docs/ja/specdojo/rulebooks/utc-index-rulebook.md +49 -144
  249. package/docs/ja/specdojo/rulebooks/utc-rulebook.md +67 -155
  250. package/docs/ja/specdojo/samples/bds-sample.md +58 -71
  251. package/docs/ja/specdojo/samples/bes-index-sample.md +20 -37
  252. package/docs/ja/specdojo/samples/bes-sample.md +43 -53
  253. package/docs/ja/specdojo/samples/bps-sample.md +42 -54
  254. package/docs/ja/specdojo/samples/br-sample.md +40 -52
  255. package/docs/ja/specdojo/samples/ccd-sample.md +0 -1
  256. package/docs/ja/specdojo/samples/cdr-sample.md +78 -0
  257. package/docs/ja/specdojo/samples/cdsd-sample.md +47 -63
  258. package/docs/ja/specdojo/samples/clis-sample.md +70 -77
  259. package/docs/ja/specdojo/samples/dec-sample.md +2 -3
  260. package/docs/ja/specdojo/samples/ifx-api-sample.yaml +0 -2
  261. package/docs/ja/specdojo/samples/ifx-msg-sample.yaml +0 -2
  262. package/docs/ja/specdojo/samples/job-sequence.yaml +67 -0
  263. package/docs/ja/specdojo/samples/mip-index-sample.md +98 -20
  264. package/docs/ja/specdojo/samples/pm-communication-plan-sample.md +26 -19
  265. package/docs/ja/specdojo/samples/pm-organization-sample.md +39 -50
  266. package/docs/ja/specdojo/samples/pm-plan-sample.md +61 -67
  267. package/docs/ja/specdojo/samples/pm-quality-management-plan-sample.md +31 -45
  268. package/docs/ja/specdojo/samples/pm-raci-sample.md +31 -37
  269. package/docs/ja/specdojo/samples/prj-assumptions-constraints-dependencies-sample.md +32 -48
  270. package/docs/ja/specdojo/samples/prj-charter-sample.md +42 -59
  271. package/docs/ja/specdojo/samples/prj-comparison-of-alternatives-sample.md +55 -61
  272. package/docs/ja/specdojo/samples/prj-success-criteria-and-acceptance-criteria-sample.md +30 -33
  273. package/docs/ja/specdojo/samples/sf-index-sample.md +13 -55
  274. package/docs/ja/specdojo/samples/sf-sample.md +73 -85
  275. package/docs/ja/specdojo/samples/sld-sample.md +60 -79
  276. package/docs/ja/specdojo/samples/uis-sample.md +98 -121
  277. package/docs/ja/specdojo/standards/job-definition-standard.md +24 -9
  278. package/docs/ja/specdojo/templates/cdr-template.md +58 -0
  279. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +2 -1
  280. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +42 -5
  281. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +35 -0
  282. package/docs/specdojo/schemas/v1/job-run.schema.yaml +23 -0
  283. package/docs/specdojo/schemas/v1/job.schema.yaml +63 -2
  284. package/docs/specdojo/schemas/v1/sch-strategy.schema.yaml +2 -2
  285. package/package.json +9 -6
  286. package/templates/antigravity/orchestrator.md +4 -1
  287. package/templates/claude/agents/specdojo-orchestrator.md +4 -1
  288. package/templates/codex/agents/specdojo-orchestrator.toml +4 -1
  289. package/templates/codex/orchestrator.md +4 -1
  290. package/templates/init-exec-defaults.yaml +13 -0
  291. package/templates/lefthook/tools/specdojo-pre-commit.mjs +8 -0
  292. package/templates/opencode/agents/specdojo-orchestrator.md +5 -2
@@ -16,7 +16,7 @@ External Integration Test Catalog (ETC) Index Documentation Rules
16
16
  本ドキュメントは、外部結合テストカタログ(ETC)の全体概要 `etc-index` を統一形式で記述するためのルールです。
17
17
  TSPに基づき、外部結合テストに共通するルールや方針を定義します。
18
18
 
19
- 個別 外部結合テストカタログ(`etc-<term>`)の記述ルールは `etc-rulebook.md` を参照してください。
19
+ 対象別カタログ(`etc-<term>`)は [[specdojo:etc-rulebook|外部結合テストカタログ 対象別 作成ルール]] に従います。
20
20
 
21
21
  ## 1. 全体方針
22
22
 
@@ -25,11 +25,11 @@ TSPに基づき、外部結合テストに共通するルールや方針を定
25
25
 
26
26
  - `etc-index` は **「考え方・共通方針・共通定義」** を記述する(個別ケースは持たない)
27
27
  - 個別の観点・条件・ケースは **`etc-<term>` に集約**し、詳細は **テストコード/CI証跡** に寄せる
28
- - 記述は **レビュー可能**であることを優先し、長文化を避ける(方針は箇条書き中心)
29
28
  - 「例外」や「対象外」を明示し、外部結合テストの責任境界(何をやらないか)を固定する
30
29
  - `tsp-index` の方針を根拠として、外部結合テストに共通する **分割基準・観点/条件の立て方・外部依存境界・合格基準・証跡** を定義する
31
30
  - 外部結合テストの目的は「**システム境界を跨ぐ結合(外部サービス/外部端末/外部環境)を含む振る舞い**を、実運用に近い前提で検証すること」である
32
31
  (ただし、再現性・コスト・安全性の観点で「実疎通」を必須化しない領域は明確に除外する)
32
+ - **共通の運用**: 役割の割り当ては適用先のメンバー定義に、`status` の昇格と承認、改訂と廃止、未決事項の登録簿への引き継ぎは [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従います。文書の整形・lint はリポジトリの検証で扱い、業務の検証に含めません。
33
33
 
34
34
  ## 2. 位置づけ(他ドキュメントとの関係)
35
35
 
@@ -57,30 +57,23 @@ flowchart BT
57
57
 
58
58
  ## 3. ファイル命名・ID規則
59
59
 
60
- - 本ルールの対象ドキュメントの `id` は `etc-index` 固定。対象別は `etc-<term>`(詳細は `etc-rulebook.md`)。
60
+ - 本ルールの対象ドキュメントの `id` は `etc-index` 固定。対象別は `etc-<term>` とします。
61
61
  - ファイル名は `etc-010-外部結合テストカタログ-概要.md` 等、プロジェクト内で一意になるように命名します。
62
- - `<term>` は用語集(GL)の論理名キー(英小文字kebab-case)を用いる(表示名は title に日本語で記載してよい)。
62
+ - `<term>` は用語集(GL)の論理名キー(英小文字kebab-case)を用いる(表示名は本文の H1 に日本語で記載してよい)。
63
63
 
64
64
  ## 4. 推奨 Frontmatter 項目
65
65
 
66
66
  ### 4.1. 設定内容
67
67
 
68
- Frontmatter は共通スキーマに従います(参照: [docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml](../../../specdojo/schemas/v1/deliverable-frontmatter.schema.yaml) / [document-metadata-standard.md](../standards/document-metadata-standard.md))。
68
+ 許可キー・必須項目・型制約は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] と `docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml` を正本とします。
69
69
 
70
- | 項目 | 説明 | 必須 |
71
- | ---------- | -------------------------------------------------- | ---- |
72
- | id | `etc-index`(固定) | ○ |
73
- | type | `test` 固定 | ○ |
74
- | title | 外部結合テストカタログ: 概要(`<システム名>`) | ○ |
75
- | status | `draft` / `ready` / `deprecated` | ○ |
76
- | based_on | 根拠となる仕様ID(ID配列。未指定時は `[]` を許容) | 任意 |
77
- | supersedes | 置き換え関係(ID配列。未指定時は `[]` を許容) | 任意 |
70
+ - メタ情報は `specdojo:` 配下に置き、`id: etc-index`、`type: test`、`rulebook: specdojo:etc-index-rulebook` を指定します。
71
+ - 文書名は本文の H1 に「外部結合テストカタログ: 概要(対象システム名)」と記載します。
78
72
 
79
73
  ### 4.2. 推奨ルール
80
74
 
81
75
  - `based_on` には最低限 `tsp-index` を含めます。
82
76
  - BAC/NFR/BR 等は、`etc-index` の方針判断(外部依存境界・共通合格基準・環境前提)に **直接利用したものだけ**を `based_on` に列挙します。
83
- - `based_on` / `supersedes` は ID 配列(未指定は `[]` 可)。
84
77
 
85
78
  ## 5. 本文構成(標準テンプレ)
86
79
 
@@ -98,35 +91,19 @@ Frontmatter は共通スキーマに従います(参照: [docs/specdojo/schema
98
91
  | 8 | ケース表の共通カラム | ○ |
99
92
  | 9 | メモ / 将来課題 | 任意 |
100
93
 
101
- 注意:次章の記述ガイドのMarkdown見出しはルール文章内の参照用であり、
102
- 生成する `etc-index` 本文の見出しは各章で指定された **番号付き** の形式
103
- (例: `## 6.`, `### 6.1.` / `#### 6.1.1.` / `#### 6.1.2.`)に置き換えてください。
94
+ 記述ガイドの各節は上表の同名の章に対応します。成果物では上表の番号を用い、`## 1. 本ドキュメントの目的と適用対象` から始めます。
104
95
 
105
96
  ## 6. 記述ガイド
106
97
 
107
98
  ### 6.1. 本ドキュメントの目的と適用対象
108
99
 
109
- 生成する `etc-index` 本文の見出しは **## 1. 本ドキュメントの目的と適用対象**
110
-
111
- 本節では、`etc-index` が **何のために存在し、何に適用されるか** を明確にします。
112
-
113
100
  - 目的:`etc-<term>` を同一基準で作成し、品質・粒度・責任範囲を揃える
114
101
  - 適用対象:外部結合テスト(ET)に関するカタログ群(`etc-index` / `etc-<term>`)
115
102
  - 非適用:総合/受入(ST/AT)のルールはそれぞれの `stc-index` / `atc-index` で扱う
116
- - 成果物の位置づけ:
117
- - `etc-index`:外部結合テスト共通方針(SSOT)
118
- - `etc-<term>`:対象別の観点・条件・ケース表(SSOT)
119
- - テストコード/CI:実装と実行証跡(Evidence)
120
-
121
- - SSOTの一次情報は `etc-index` / `etc-<term>` とし、テストコード/CIは **実装と実行結果の証跡** として扱う
122
- - 本書が扱う粒度:**判断基準・共通ルールまで**(個別ケースの列挙は禁止)
103
+ - カタログを仕様の正本、テストコード/CIを実装と実行結果の証跡とし、使い分けを示す
123
104
 
124
105
  ### 6.2. テスト対象の括り方と分割基準
125
106
 
126
- 生成する `etc-index` 本文の見出しは **## 2. テスト対象の括り方と分割基準**
127
-
128
- 本節では、`etc-<term>` の `<term>` をどう切るか(対象単位の設計)を定義します。
129
-
130
107
  - `<term>` は「**外部境界を跨ぐ結合のまとまり**」を単位とする
131
108
  例:外部決済連携、外部IdP認証、外部通知(メール/SMS)、外部ファイル連携(S3等)、端末機能連携 など
132
109
  - 分割基準(推奨順):
@@ -144,10 +121,6 @@ Frontmatter は共通スキーマに従います(参照: [docs/specdojo/schema
144
121
 
145
122
  ### 6.3. 対象外・除外理由(共通)
146
123
 
147
- 生成する `etc-index` 本文の見出しは **## 3. 対象外・除外理由(共通)**
148
-
149
- 本節では、外部結合テスト(ET)で **やらないこと** と、その **理由**、および **例外条件** を明確にします。
150
-
151
124
  #### 6.3.1. 記述ルール
152
125
 
153
126
  - 形式は **「対象外(何をやらないか)」「除外理由(なぜやらないか)」「代替」「例外(ETで扱う条件)」** を基本とする
@@ -157,20 +130,19 @@ Frontmatter は共通スキーマに従います(参照: [docs/specdojo/schema
157
130
 
158
131
  #### 6.3.2. 推奨フォーマット(表)
159
132
 
160
- | 対象外(やらないこと) | 除外理由 | 代替レベル/代替手段 | 例外(ETで扱う条件) |
161
- | ---------------------- | -------- | ------------------- | -------------------- |
133
+ | 対象外(やらないこと) | 除外理由 | 代替レベル/代替手段 | 例外(ETで扱う条件) |
134
+ | ---------------------- | ------------------------ | ------------------- | ---------------------------------------- |
135
+ | 本番決済口座への実課金 | 顧客残高を変動させるため | 決済sandbox | 監査済みの限定リハを別計画で行う場合のみ |
162
136
 
163
137
  #### 6.3.3. 典型例(記載候補)
164
138
 
165
- - 長時間耐久・大規模負荷(スループット/長時間稼働/Soak)
166
- - 本番実アカウント/本番実データに依存する検証(安全性・個人情報)
167
- - 端末群・多ブラウザの網羅(互換性はST/ATや別計画へ)
168
- - 外部サービスの品質そのもの(外部障害の責任切り分け)
139
+ - 長時間耐久・大規模負荷:測定条件と実行コストが異なるため、NFR/性能試験計画で扱う。ETでの例外なし
140
+ - 本番実アカウント/本番実データ:安全性・個人情報・運用影響のため、受入/本番リハの別計画で扱う。例外は監査済みの限定リハのみ
141
+ - 端末群・多ブラウザの網羅:組合せが増え外部境界の検証から逸れるため、ST/ATや互換性試験計画で扱う。ETでの例外は重大不具合の再現に限定
142
+ - 外部サービス自体の品質・SLA:責任境界外で原因切り分けが困難なため、監視/運用・ベンダ連携で扱う。ETでの例外なし
169
143
 
170
144
  ### 6.4. 観点の立て方(共通)
171
145
 
172
- 生成する `etc-index` 本文の見出しは **## 4. 観点の立て方(共通)**
173
-
174
146
  観点(Perspective)は「外部境界を跨いだときに何を保証するか」の切り口であり、対象別カタログの章立てとして用います。
175
147
 
176
148
  - 観点の型(最低限この順で検討):
@@ -187,8 +159,6 @@ Frontmatter は共通スキーマに従います(参照: [docs/specdojo/schema
187
159
 
188
160
  ### 6.5. 条件の立て方(共通)
189
161
 
190
- 生成する `etc-index` 本文の見出しは **## 5. 条件の立て方(共通)**
191
-
192
162
  条件(Condition)は、観点を確認するための前提状態・入力状態・環境条件のバリエーションです。
193
163
  ETでは「外部のふるまい」や「環境差」が条件になりやすいため、以下の分解で作成します。
194
164
 
@@ -205,10 +175,6 @@ ETでは「外部のふるまい」や「環境差」が条件になりやすい
205
175
 
206
176
  ### 6.6. 観点/条件の採用基準と対象別への分配方針(共通)
207
177
 
208
- 生成する `etc-index` 本文の見出しは **## 6. 観点/条件の採用基準と対象別への分配方針(共通)**
209
-
210
- 本節では、観点/条件を「採用する判断」と「`etc-<term>` へ割り当てる判断」を共通ルールとして定義します。
211
-
212
178
  #### 6.6.1. 採用基準(共通)
213
179
 
214
180
  - 観点は「1観点=1合否命題」で採用する(複数命題の混在を禁止)
@@ -228,15 +194,13 @@ ETでは「外部のふるまい」や「環境差」が条件になりやすい
228
194
 
229
195
  推奨フォーマット(例):
230
196
 
231
- | 観点/条件 | 採用理由 | 主担当 `etc-<term>` | 従担当(任意) | 備考 |
232
- | --------- | -------- | ------------------- | -------------- | ---- |
197
+ | 観点/条件 | 採用理由 | 主担当 `etc-<term>` | 従担当(任意) | 備考 |
198
+ | ---------------------------- | -------------- | --------------------- | -------------- | -------------- |
199
+ | 再送と冪等性/同一キーで再送 | 二重課金の防止 | `etc-payment-gateway` | なし | 課金件数を観測 |
233
200
 
234
201
  ### 6.7. 外部結合テスト共通の境界/依存/環境の扱い
235
202
 
236
- 生成する `etc-index` 本文の見出しは **## 7. 外部結合テスト共通の境界/依存/環境の扱い**
237
-
238
- 外部結合テストでは「外部依存がある前提」で、再現性と安全性を両立する必要があります。
239
- 本節で共通方針(どこまで実、どこから疑似)を定めます。
203
+ 実疎通と疑似化で担保する観点を分け、再現性と安全性を両立する共通方針を定めます。
240
204
 
241
205
  - 外部サービス接続:
242
206
  - 原則:**sandbox / test environment** を使用し、実運用相当の契約を検証する
@@ -259,8 +223,6 @@ ETでは「外部のふるまい」や「環境差」が条件になりやすい
259
223
 
260
224
  ### 6.8. ケース表の共通カラム
261
225
 
262
- 生成する `etc-index` 本文の見出しは **## 8. ケース表の共通カラム**
263
-
264
226
  `etc-<term>` の末端(条件・ケース表)は、検索性・比較性・自動化移行の容易さを確保するため、
265
227
  全termで同一カラム順を採用します。
266
228
 
@@ -272,7 +234,7 @@ ETでは「外部のふるまい」や「環境差」が条件になりやすい
272
234
 
273
235
  - `条件`:入力/状態/環境の要点(`入力:` `状態:` `環境:` の形を推奨)
274
236
  - `手順(最小)`:抽象化した最小手順(クリック列挙禁止)
275
- - `期待値`:判定可能な合格条件(観測点を含める)
237
+ - `期待値`:判定可能な合格条件(観測点を含め、「エラーにならないこと」だけで済ませない)
276
238
 
277
239
  推奨カラム(運用必須):
278
240
 
@@ -285,10 +247,8 @@ ETでは「外部のふるまい」や「環境差」が条件になりやすい
285
247
 
286
248
  ### 6.9. メモ / 将来課題
287
249
 
288
- 生成する `etc-index` 本文の見出しは **## 9. メモ / 将来課題**
289
-
290
- 本節は、現時点で決めきれない事項や将来の改善点を記録します。
291
- ただし、運用ルールとして必須な内容は本節に置かず、本文(1〜8章)へ反映します。
250
+ 未決事項がある場合に、論点・外部結合テストへの影響・当面の扱いを記録します。
251
+ 決定済みの必須方針は対応する本文の章へ反映します。
292
252
 
293
253
  - 将来検討(例):
294
254
  - 外部I/Fの擬似化方針の標準化(sandbox不安定時のfallback)
@@ -302,79 +262,19 @@ ETでは「外部のふるまい」や「環境差」が条件になりやすい
302
262
  | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
303
263
  | `etc-index` に個別ケース(条件・手順・期待値)を大量に列挙する | `etc-index` は共通方針のSSOTであり、個別は `etc-<term>` に集約するため |
304
264
  | 外部サービス実疎通を無条件に必須化し、再現性・コスト・安全性を無視する | CI不安定・費用増・情報漏洩リスクになり、運用不能になるため(例外基準が必要) |
305
- | 秘密情報(token/secret)を本文や証跡に平文で残す | セキュリティ事故につながるため |
306
265
  | 手順にUI操作のクリック列挙を書く(末端表でも過剰な操作手順を書く) | ETの焦点が外部境界なのに、E2E/UIの責務と混ざり保守性が低下するため |
307
- | 期待値を「エラーにならないこと」など曖昧に書く | 判定不能で合否が揺れ、証跡として機能しないため |
308
266
  | `case_id` を後から変更する(参照があるのに変更する) | トレース・証跡リンクが壊れ、履歴追跡が不能になるため |
309
267
  | 対象外・除外理由(共通)と矛盾するケースを `etc-<term>` に記載する | 責任境界が崩れるため(例外は根拠と条件を明記) |
310
268
 
311
269
  ## 8. サンプル(最小)
312
270
 
313
- 注:以下はルール文書内の例示です。生成する `etc-index` では `## 1...` から始まります。
314
-
315
- ```yaml
316
- ---
317
- id: etc-index
318
- type: test
319
- title: 外部結合テストカタログ: 概要
320
- status: draft
321
- based_on: [tsp-index]
322
- supersedes: []
323
- ---
324
- ```
325
-
326
- ### 8.1. 本ドキュメントの目的と適用対象
327
-
328
- 本ドキュメントは、外部結合テストカタログ(ETC)の全体概要 `etc-index` を統一形式で記述するためのルールである。
329
- `etc-index` は外部結合テストに共通する「対象単位の切り方」「観点/条件の立て方」「外部依存境界」「合格基準」「証跡方針」を定義し、
330
- 対象別カタログ `etc-<term>` の作成と運用の基盤とする。
331
-
332
- ### 8.2. テスト対象の括り方と分割基準
333
-
334
- `etc-<term>` の `<term>` は外部境界を跨ぐ結合(外部サービス/外部環境)のまとまりとする。
335
- 分割は外部I/F境界・失敗モード・合格基準・運用責任を基準とし、過分割と肥大化の双方を避ける。
336
- 外部I/Fや環境前提が混在する場合は分割候補とする。
337
-
338
- ### 8.3. 対象外・除外理由(共通)
339
-
340
- 外部結合テスト(ET)では、外部依存を含む振る舞いを確認する一方で、以下は原則として対象外とする。
341
-
342
- | 対象外(やらないこと) | 除外理由 | 代替レベル/代替手段 | 例外(ETで扱う条件) |
343
- | ------------------------------------------- | ------------------------------------------ | ------------------------- | ---------------------------- |
344
- | 長時間耐久・大規模負荷(Soak/高負荷) | 測定条件設計が別物で、実行コストが高い | NFR/性能試験計画 | なし |
345
- | 本番実アカウント/本番実データに依存する検証 | 安全性・個人情報・運用影響リスクが高い | 受入/本番リハ(別計画) | 監査済みの限定リハのみ |
346
- | 多ブラウザ/多端末の網羅 | 組合せ爆発でETの目的(外部境界)から逸れる | ST/ATまたは互換性試験計画 | 重大不具合の再現ケースに限定 |
347
- | 外部サービス品質そのもの(外部側のSLA保証) | 責任境界外で、原因切り分けが困難 | 監視/運用、ベンダ連携 | なし |
348
-
349
- ### 8.4. 観点の立て方(共通)
350
-
351
- 観点は「外部I/F契約」「認証/認可」「失敗モード」「冪等性/再送」「データ整合性」「運用性」を基軸に立てる。
352
- 観点名は「名詞+品質/振る舞い」で統一し、条件を複数持てる程度の粒度にまとめる。
271
+ 決済連携の「外部結合テスト共通の境界/依存/環境の扱い」の記述例(抜粋)です。
353
272
 
354
- ### 8.5. 条件の立て方(共通)
273
+ ```markdown
274
+ ## 7. 外部結合テスト共通の境界/依存/環境の扱い
355
275
 
356
- 条件は入力・状態・環境に分解し、代表→境界→重大例外の順で追加する。
357
- 直積は原則作らず、必要時のみ理由と管理方法(データセット参照等)を明記する。
358
-
359
- ### 8.6. 観点/条件の採用基準と対象別への分配方針(共通)
360
-
361
- 観点/条件は、業務影響・境界/失敗モードの重要性・上位仕様根拠を基準に採用する。
362
- 分配は境界/外部I/F・失敗モード・運用責任を基準に主担当 `etc-<term>` を1つ定め、重複は例外として扱う。
363
- 分配結果は `etc-<term>` のケース表とトレース列で追跡可能にする。
364
-
365
- ### 8.7. 外部結合テスト共通の境界/依存/環境の扱い
366
-
367
- 外部結合テストでは、原則sandbox等のテスト環境で外部契約を検証しつつ、
368
- 再現性が崩れる場合はスタブ/モックを併用する(担保範囲の分担を明記する)。
369
- 秘密情報は安全に管理し、ログ出力禁止とする。冪等性/再送/タイムアウト境界は標準観点とする。
370
-
371
- ### 8.8. ケース表の共通カラム
372
-
373
- 対象別カタログ `etc-<term>` の末端表は、全termで共通のカラム順を採用する。
374
- 必須:case_id / 条件 / 手順(最小) / 期待値
375
- 推奨:観測点(アサーション)/ 境界・依存 / トレース / 優先度 / 自動化 / 証跡
376
-
377
- ### 8.9. メモ / 将来課題
378
-
379
- 将来検討事項(例):sandbox不安定時の標準fallback、テストデータ廃棄、ログ/トレースリンク統一、ETの実行時間上限と分割基準等を記録する。
380
- 運用ルールとして必須になった時点で本文へ昇格させる。
276
+ - 決済APIの契約・認証は事業者のsandboxで確認する。障害応答が再現できない場合はスタブで429・タイムアウトを返し、再送を検証する。
277
+ - 応答待ちは2秒、再送は1回を上限とし、同じ冪等キーで再送して課金が1件に留まることを確認する。
278
+ - 実行ごとの接頭辞でテストデータを分離する。テスト用資格情報はCIのsecret管理から取得し、相関IDだけをログに残す。
279
+ - 証跡はCI runに外部リクエストID・相関ID・課金件数を関連付け、失敗時にも照合できるようにする。
280
+ ```
@@ -13,25 +13,19 @@ specdojo:
13
13
 
14
14
  External Integration Test Catalog (ETC) Documentation Rules
15
15
 
16
- 本ドキュメントは、外部結合テストカタログ(ETC)の対象別 `etc-<term>` を統一形式で記述するためのルールです。
17
- `etc-index` を前提に、SSOTの本体として、対象ごとの **外部結合の責務・境界・外部依存/環境、観点 x 条件=ケース、トレース、証跡** を明文化します。
16
+ 対象別の外部結合テストカタログ `etc-<term>` について、結合責務・境界・環境、観点と条件から作るケース、トレース・証跡の記述基準を定めます。
18
17
 
19
18
  ## 1. 全体方針
20
19
 
21
- 個別 ETC(`etc-<term>`)は、外部結合テストにおける SSOT の本体として、対象ごとの結合責務と境界を明確化し、
22
- 観点×条件=ケース(末端表)を最小情報で整理して、テストコード/CI証跡へ確実に接続できる形で記述する。
23
-
24
20
  - `etc-<term>` は **対象固有の情報のみ** を記述し、共通ルールは `etc-index` を参照する(重複記述しない)
25
21
  - 外部結合テストの目的は「**外部境界を跨いだ結合の振る舞い**を、実運用に近い前提で検証すること」である
26
- - ケースは「表の1行=1テスト」とし、手順と期待値は **判定可能**な粒度で簡潔に書く
27
- - 直積(全組合せ)を原則避け、代表→境界→重大例外の順で増やす(必要時は理由・範囲を明記)
22
+ - ケースは代表→境界→重大例外の順で増やし、直積が必要な場合は理由・範囲を明記する
28
23
  - 外部依存(sandbox/スタブ/モック)・テストデータ・秘密情報の扱いは、再現性と安全性を優先して固定する
29
24
  - すべての観点・ケースは、根拠仕様(`based_on` / `トレース`)と、証跡(テストコード/CI/外部リクエストID/ログ相関キー等)に接続されていること
25
+ - **共通の運用**: 役割の割り当ては適用先のメンバー定義に、`status` の昇格と承認、改訂と廃止、未決事項の登録簿への引き継ぎは [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従う。文書の整形・lint はリポジトリの検証で扱い、業務の検証に含めない。
30
26
 
31
27
  ## 2. 位置づけ(他ドキュメントとの関係)
32
28
 
33
- 個別 ETC(`etc-<term>`)と他ドキュメントの関係を示します。
34
-
35
29
  ```mermaid
36
30
  flowchart BT
37
31
  TSP["tsp-index<br>テスト戦略・方針"]
@@ -56,34 +50,22 @@ flowchart BT
56
50
 
57
51
  - `id` は `etc-<term>`(kebab-case。例: `etc-payment-gateway`)。
58
52
  - ファイル名は `etc-010-外部結合テストカタログ-<term>.md` 等(例: `etc-010-外部結合テストカタログ-決済ゲートウェイ.md`)。
59
- - `<term>` は用語集(GL)の論理名キー(英小文字kebab-case)を用いる(表示名は title / ファイル名で日本語を使用してよい)。
53
+ - `<term>` は用語集(GL)の論理名キー(英小文字kebab-case)を用いる(表示名は本文の H1 / ファイル名で日本語を使用してよい)。
60
54
 
61
55
  ## 4. 推奨 Frontmatter 項目
62
56
 
63
57
  ### 4.1. 設定内容
64
58
 
65
- Frontmatter は共通スキーマに従います(あわせてドキュメントのメタ情報の記述ルールも参照)。
66
-
67
- - 参照スキーマ: [docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml](../../../specdojo/schemas/v1/deliverable-frontmatter.schema.yaml)
68
- - メタ情報標準: [document-metadata-standard.md](../standards/document-metadata-standard.md)
59
+ 許可キー・必須項目・型制約は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] と `docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml` を正本とする。
69
60
 
70
- | 項目 | 説明 | 必須 |
71
- | ---------- | -------------------------------------------------------------------------------- | ---- |
72
- | id | ETC ID(個別: `etc-<term>`) | ○ |
73
- | type | `test` 固定 | ○ |
74
- | title | 外部結合テストカタログ: <対象名> | ○ |
75
- | status | `draft` / `ready` / `deprecated` | ○ |
76
- | based_on | 根拠仕様(最低限: `tsp-index`, `etc-index`。対象固有の根拠は本文トレースに集約) | ○ |
77
- | part_of | 集約ドキュメントへの所属(ID配列) | 任意 |
78
- | supersedes | 置き換え関係 | 任意 |
61
+ - メタ情報は `specdojo:` 配下に置き、`id: etc-<term>`、`type: test`、`rulebook: specdojo:etc-rulebook` を指定する。
62
+ - 文書名は本文の H1 に「外部結合テストカタログ: <対象名>」と記載する。
79
63
 
80
64
  ### 4.2. 推奨ルール
81
65
 
82
- - `based_on` には **本対象の外部結合テスト観点の根拠となる仕様** を列挙します。
83
66
  - `based_on` は原則 `[tsp-index, etc-index]` を最低限とし、対象固有の根拠(`br-*` / `bac-*` / `spec-*` / `nfr-*` 等)は本文「トレース」に集約します。
84
67
  - 機械処理上の都合で `based_on` にも列挙する場合は、本文トレースと矛盾しないこと。
85
68
  - 記述内容が多くなる場合は、ドキュメントを分割し、`part_of` で集約ドキュメントに所属させます。
86
- - `part_of` / `based_on` / `supersedes` は ID 配列(未指定は `[]` 可)。
87
69
 
88
70
  ## 5. 本文構成(標準テンプレ)
89
71
 
@@ -99,18 +81,12 @@ Frontmatter は共通スキーマに従います(あわせてドキュメン
99
81
  | 6 | テスト観点とケース | ○ |
100
82
  | 7 | 実行運用メモ(データ/後始末/制約) | 任意 |
101
83
 
102
- 注意:次章の記述ガイドのMarkdown見出しはルール文章内の参照用であり、
103
- 生成する `etc-<term>` 本文の見出しは各章で指定された **番号付き** の形式
104
- (例: `## 6.`, `### 6.1.` / `#### 6.1.1.` / `#### 6.1.2.`)に置き換えてください。
84
+ 記述ガイドの各節は上表の同名の章に対応する。成果物は `## 1. 概要(<term>)` から始め、「テスト観点とケース」の配下は `### 6.1. 観点:<観点>`、`#### 6.1.1. 意図`、`#### 6.1.2. 条件・ケース表` とする。
105
85
 
106
86
  ## 6. 記述ガイド
107
87
 
108
88
  ### 6.1. 概要(`<term>`)
109
89
 
110
- 生成する `etc-<term>` 本文の見出しは **## 1. 概要(&lt;term&gt;)**
111
-
112
- 本節では、対象(`<term>`)が何であり、どの外部境界を跨ぐ結合を本カタログで扱うかを簡潔に示します。
113
-
114
90
  - `<term>` の説明(1〜3行):外部境界・連携対象・主たるユースケースが分かるように書く
115
91
  - 期待する利用者:レビューア/実装者/テスト実装者/運用者が前提を把握できる内容にする
116
92
  - 対象の粒度:`etc-index` の分割基準に従い、過分割/肥大化を避ける
@@ -119,10 +95,6 @@ Frontmatter は共通スキーマに従います(あわせてドキュメン
119
95
 
120
96
  ### 6.2. 責務
121
97
 
122
- 生成する `etc-<term>` 本文の見出しは **## 2. 責務**
123
-
124
- 本節では、「この外部結合が何を保証すべきか(ETで確認する責務)」を列挙します。
125
-
126
98
  - 箇条書きで 3〜7 個程度を目安に、**動詞で始まる**形で記述する
127
99
  - 例:外部I/F契約に従って送受信する/署名を検証する/再送時に冪等性を満たす/失敗時に再試行する/相関IDを出力する
128
100
 
@@ -133,10 +105,7 @@ Frontmatter は共通スキーマに従います(あわせてドキュメン
133
105
 
134
106
  ### 6.3. 対象外
135
107
 
136
- 生成する `etc-<term>` 本文の見出しは **## 3. 対象外**
137
-
138
- 本節では、「この対象カタログ(`etc-<term>`)ではやらないこと」を明示します。
139
- `etc-index` の「対象外・除外理由(共通)」と矛盾しないことが前提です。
108
+ `etc-index` の「対象外・除外理由(共通)」に従い、対象固有の除外を示します。
140
109
 
141
110
  - 対象外は「なぜ除外するか(理由)」とセットで書く
142
111
  - 可能なら「代替するレベル」(IT/ST/AT/NFR 等)も併記する
@@ -149,10 +118,6 @@ Frontmatter は共通スキーマに従います(あわせてドキュメン
149
118
 
150
119
  ### 6.4. 境界/依存/環境
151
120
 
152
- 生成する `etc-<term>` 本文の見出しは **## 4. 境界/依存/環境**
153
-
154
- 本節では、外部結合テストにおける「境界(どこまでが対象か)」「依存(外部要因)」「環境前提」を明確にします。
155
-
156
121
  - 境界:対象の入口/出口(API、Webhook、Queue、Batch、SDK、外部コール)を明記する
157
122
  - 外部依存はカテゴリごとに列挙し、「扱い(sandbox/実/スタブ/モック)」と「観測点」を決める
158
123
  - 外部API:sandbox/スタブ(成功/4xx/5xx/タイムアウト/レート制限)
@@ -166,14 +131,11 @@ Frontmatter は共通スキーマに従います(あわせてドキュメン
166
131
 
167
132
  ### 6.5. トレース
168
133
 
169
- 生成する `etc-<term>` 本文の見出しは **## 5. トレース**
170
-
171
- 本節では、`etc-<term>` の根拠となる上位成果物との対応関係(トレーサビリティ)を示します。
172
- 本カタログにおけるトレースの一次情報(SSOT)は **`## 5. トレース`** とし、観点・ケース表では **trace_key(`TR-xx`)参照** に統一します。
134
+ 根拠仕様との対応の正本は「トレース」とし、観点・ケースは `trace_key`(`TR-xx`)で参照します。
173
135
 
174
- #### 6.5.1. 記述ルール(trace_key)
136
+ #### 6.5.1. 記述ルール(`trace_key`)
175
137
 
176
- - 各トレース項目に **trace_key(`TR-xx`)** を付与する(例:`TR-01`…)
138
+ - 各トレース項目に **`trace_key`(`TR-xx`)** を付与する(例:`TR-01`…)
177
139
  - `trace_key` は **本ドキュメント内で一意**で、原則変更しない(削除しても欠番は詰めない)
178
140
  - 観点・ケース表の `トレース` 列には **仕様IDを直書きせず** `TR-xx` を列挙する
179
141
  - 新しい根拠が必要になった場合は、**先に本節の表へ追加**し、付与された `trace_key` をケース表で参照する
@@ -189,28 +151,20 @@ Frontmatter は共通スキーマに従います(あわせてドキュメン
189
151
 
190
152
  ### 6.6. テスト観点とケース
191
153
 
192
- 生成する `etc-<term>` 本文の見出しは **## 6. テスト観点とケース**
193
-
194
- 本節は `etc-<term>` の中心です。観点(見出し)→ ケース表(末端表)の順で構成します。
154
+ 観点(見出し)→ 意図 → 条件・ケース表の順で構成します。
195
155
 
196
156
  #### 6.6.1. 観点:<観点>
197
157
 
198
- 生成する `etc-<term>` 本文の見出しは **### 6.1. 観点:<観点>**
199
-
200
158
  - 観点は `etc-index` の「観点の立て方(共通)」に従って命名する
201
159
  - 観点の粒度は「条件が複数ぶら下がる」程度にまとめる(細かすぎる観点の乱立を避ける)
202
160
  - 観点名(見出し)は改善のため変更してよいが、`perspective_key` は原則変更しない
203
161
 
204
162
  ##### 6.6.1.1. 意図
205
163
 
206
- 生成する `etc-<term>` 本文の見出しは **#### 6.1.1. 意図**
207
-
208
164
  - 観点ごとに「意図(この観点で保証すること)」を 1〜2 行で書く
209
165
 
210
166
  ##### 6.6.1.2. 条件・ケース表
211
167
 
212
- 生成する `etc-<term>` 本文の見出しは **#### 6.1.2. 条件・ケース表**
213
-
214
168
  - ケース表の 1 行は「1テスト」を表す(条件×期待値が一意)
215
169
  - 必須カラムは `etc-index` の定義に従う
216
170
  - `case_id` は以下を推奨し、変更しない
@@ -224,12 +178,8 @@ Frontmatter は共通スキーマに従います(あわせてドキュメン
224
178
  - 期待値は判定可能に書く(外部レスポンス、外部ID、内部状態、イベント、ログ相関など観測点を含める)
225
179
  - 証跡はテストコードとCI実行結果へ接続できる形で書く(加えて外部リクエストIDやログ相関キー等を推奨)
226
180
 
227
- 推奨:観点ごとのケース数は「代表→境界→重大例外」の順で増やし、直積(全組合せ)を原則避ける
228
-
229
181
  ### 6.7. 実行運用メモ(任意)
230
182
 
231
- 生成する `etc-<term>` 本文の見出しは **## 7. 実行運用メモ(データ/後始末/制約)**
232
-
233
183
  - テストデータの作り方/namespace/削除手順
234
184
  - 失敗時のリトライ手順・外部側の後始末(取消、返金、無効化等)
235
185
  - 実行制約(並列不可、回数制限、実行時間帯、レート制限)
@@ -241,7 +191,6 @@ Frontmatter は共通スキーマに従います(あわせてドキュメン
241
191
  | ---------------------------------------------------------------------------------- | ------------------------------------------------------------- |
242
192
  | `etc-index` の共通方針を `etc-<term>` 側で勝手に上書きする(境界/依存/対象外など) | ET全体の一貫性が崩れ、レビュー・保守が困難になるため |
243
193
  | 外部疎通を無条件に「実」必須にする(再現性・安全性・費用の判断なし) | CI不安定化・費用増・情報漏洩リスクで運用不能になるため |
244
- | 秘密情報(token/secret)を本文・証跡・ログに平文で残す | セキュリティ事故につながるため |
245
194
  | ケース表にUIクリック手順を大量に列挙する | ETの焦点が外部境界なのにE2E責務と混ざり、保守性が低下するため |
246
195
  | 期待値を曖昧に書く(例:「エラーにならないこと」「正常に動くこと」) | 合否判定ができず証跡にならないため |
247
196
  | `case_id` を変更する/再利用する | トレース・証跡リンクが破壊され、履歴追跡が不能になるため |
@@ -250,62 +199,59 @@ Frontmatter は共通スキーマに従います(あわせてドキュメン
250
199
 
251
200
  ## 8. サンプル(最小)
252
201
 
253
- 注:以下はルール文書内の例示です。生成する `etc-<term>` では `## 1...` から始まります。
202
+ 形式の輪郭を示す最小例です。仕様ID・証跡のパスは例示用で、実案件では実在する根拠・実行結果に置き換えます。
254
203
 
255
- ```yaml
204
+ ```markdown
256
205
  ---
257
- id: etc-payment-gateway
258
- type: test
259
- title: 外部結合テストカタログ: 決済ゲートウェイ(payment-gateway)
260
- status: draft
261
- part_of: []
262
- based_on: [tsp-index, etc-index]
263
- supersedes: []
206
+ specdojo:
207
+ id: etc-payment-gateway
208
+ type: test
209
+ status: draft
210
+ rulebook: specdojo:etc-rulebook
211
+ based_on: [tsp-index, etc-index]
264
212
  ---
265
- ```
266
213
 
267
- ### 8.1. 概要(payment-gateway)
214
+ # 外部結合テストカタログ: 決済ゲートウェイ
268
215
 
269
- 決済ゲートウェイとの連携(与信、確定、取消、Webhook受信)を扱う。
216
+ ## 1. 概要(payment-gateway)
270
217
 
271
- ### 8.2. 責務
218
+ 決済ゲートウェイとの与信連携を扱う。
272
219
 
273
- - 外部I/F契約に従ってリクエストを送信し、レスポンスを解釈する
274
- - Webhookを検証し、内部状態へ反映する
275
- - タイムアウト/リトライ時に冪等性を満たす
276
- - 失敗時に相関IDを含むログ/エラー情報を残す
220
+ ## 2. 責務
277
221
 
278
- ### 8.3. 対象外
222
+ - 外部I/F契約に従って与信リクエストを送受信する。
223
+ - タイムアウト後の再送で冪等性を満たす。
224
+ - 外部取引IDと相関IDで結果を追跡できるようにする。
279
225
 
280
- - 大規模負荷試験(理由:測定条件設計が別物、代替:NFR)
281
- - 多ブラウザ網羅(理由:目的外、代替:ST/AT)
226
+ ## 3. 対象外
282
227
 
283
- ### 8.4. 境界/依存/環境
228
+ - 大規模負荷試験(測定条件設計が異なるため、NFRで扱う)。
229
+ - 多ブラウザ網羅(外部境界の検証外のため、ST/ATで扱う)。
284
230
 
285
- - 境界:`POST /payments/authorize` / `POST /payments/capture` / `POST /payments/cancel` / `POST /webhooks/payment`
286
- - 外部ゲートウェイ:sandbox(成功/4xx/5xx/timeout/ratelimitを再現)
287
- - 認証:テスト用APIキー(CI secret管理、ログ出力禁止)
288
- - データ:`test-run-<runId>-*` プレフィックスで作成、終了時に取消/削除
289
- - 時刻:署名期限を含むため、許容窓(±N分)を明記
231
+ ## 4. 境界/依存/環境
290
232
 
291
- ### 8.5. トレース
233
+ - 境界:`POST /payments/authorize`。外部ゲートウェイはsandboxを使用し、タイムアウトを再現する。
234
+ - 認証:テスト用APIキーをCI secret管理から取得し、ログに出力しない。
235
+ - データ:`test-run-<runId>-*` で分離し、終了時に取消・削除する。
236
+ - 時刻:署名の許容窓を前後5分とし、テスト時計を固定する。
292
237
 
293
- | trace_key | 仕様ID | 要点 | 備考 |
294
- | --------- | ----------- | ------------------- | ---- |
295
- | TR-01 | spec-pay-01 | 与信→確定の状態遷移 | |
296
- | TR-02 | nfr-pay-03 | リトライ上限と待機 | |
238
+ ## 5. トレース
297
239
 
298
- ### 8.6. テスト観点とケース
240
+ | trace_key | 仕様ID | 要点 | 備考 |
241
+ | --------- | ---------- | ----------------------------- | ------ |
242
+ | TR-01 | nfr-pay-03 | 同一キーで再送しても与信は1件 | 例示用 |
299
243
 
300
- #### 8.6.1. 観点:再送と冪等性
244
+ ## 6. テスト観点とケース
301
245
 
302
- ##### 8.6.1.1. 意図
246
+ ### 6.1. 観点:再送と冪等性
303
247
 
304
- 外部の一時失敗やタイムアウト時でも、二重課金を防ぎ最終的に正しい状態へ収束させる。
248
+ #### 6.1.1. 意図
305
249
 
306
- ##### 8.6.1.2. 条件・ケース表
250
+ タイムアウト後の再送でも二重課金せず、最終的に与信成功へ収束させる。
307
251
 
308
- | case_id | 条件 | 手順(最小) | 期待値 | 観測点(アサーション) | 境界/依存 | トレース | 優先度 | 自動化 | 証跡 |
309
- | ---------------------------------- | -------------------------------------- | --------------------------------------- | -------------------------- | ----------------------------------- | ---------------- | -------- | ------ | --------- | ------------------------------------------------------- |
310
- | et-payment-gateway-idempotency-010 | 環境: 外部timeout → 同一冪等キーで再送 | authorize → timeout再現 → 同一keyで再送 | 二重課金なしで最終的に成功 | 外部取引ID一意、内部状態=authorized | sandbox(timeout) | TR-02 | P0 | automated | tests/et/payment/idempotency.test.ts, CI#..., reqId=... |
311
- | et-payment-gateway-idempotency-020 | 状態: Webhook重複受信 | webhookを同一payloadで2回送信 | 状態が二重更新されない | 更新回数=1、イベント重複なし | sandbox/webhook | TR-01 | P1 | automated | tests/et/payment/webhook.test.ts, CI#..., trace=... |
252
+ #### 6.1.2. 条件・ケース表
253
+
254
+ | case_id | 条件 | 手順(最小) | 期待値 | 観測点(アサーション) | 境界/依存 | トレース | 優先度 | 自動化 | 証跡 |
255
+ | ---------------------------------- | ----------------- | --------------------- | ---------------------- | ----------------------------------- | ---------------- | -------- | ------ | --------- | --------------------------------------------------- |
256
+ | et-payment-gateway-idempotency-010 | 環境: 初回timeout | 与信 → 同一キーで再送 | 与信成功、二重課金なし | 外部取引ID一意、内部状態=authorized | sandbox(timeout) | TR-01 | P0 | automated | tests/et/payment/idempotency.test.ts、CI run、reqId |
257
+ ```