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
@@ -13,108 +13,99 @@ specdojo:
13
13
 
14
14
  System Design Critical Flows Documentation Rules
15
15
 
16
- 事故や仕様誤解につながる処理に絞り、境界・永続化点・再実行性・失敗時挙動を共有するための規約である。実装、テスト、運用の詳細を複製せず、それぞれの正本と未決事項への導線を定める。
16
+ 事故や仕様誤解につながる処理の境界・永続化点・再実行性・失敗時挙動と、実装・テスト・運用の正本への導線を定める。
17
17
 
18
18
  ## 1. 全体方針
19
19
 
20
- - 一覧と詳細が扱うフローは同じ ID の集合とし、総数を最大5件とする。上限の例外は設けない。追加候補で超過する場合は既存との統合・置換・対象外への整理を先に行い、整理後も5件以内であることと選定理由を確認してから反映する。
21
- - 通常処理の網羅より、順序、排他、重複、部分成功、外部障害、人間承認を誤った場合の結果を明確にする。
22
- - 読み手が開始条件、成功の確定、失敗時に残るもの、再開の可否を判断できる粒度にする。
23
- - 値・構文・データ構造は実装、schema、リファレンスを正本とする。本書には一意な参照と確認条件だけを置く。
24
- - 設計上の要求、確認済みの動作、未確認の適合を区別する。未決の業務判断や運用条件を完成済みと扱わない。
20
+ - 一覧と詳細は同じフロー ID の集合で、例外なく最大5件とする。超過時は統合・置換・対象外を先に判断し、件数と選定理由を確認する。
21
+ - 順序・排他・重複・部分成功・外部障害・人間承認を誤る結果を、通常処理の網羅より優先する。
22
+ - 値・構文・データ構造は実装・schema・リファレンスを正本とし、一意な参照と確認条件だけを置く。
23
+ - 設計要求・確認済み動作・未確認の適合を区別し、未決の業務判断・運用条件を完成済みと扱わない。
24
+ - **共通の運用**: 役割の割り当ては適用先のメンバー定義に、`status` の昇格と承認、改訂と廃止、未決事項の登録簿への引き継ぎは [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従う。文書の整形・lint はリポジトリの検証で扱い、業務の受入確認に含めない。
25
25
 
26
26
  ## 2. 位置づけと用語定義
27
27
 
28
- | 情報 | 本書との責務境界 |
29
- | -------------------------- | ------------------------------------------------------------------------ |
30
- | システム設計索引 | 実装・設定・定義ファイルの所在と共通条件の正本。本書から参照する |
31
- | 業務フロー・状態遷移仕様 | 対象者、起動条件、状態用語の定義先。本書で状態体系を再定義しない |
32
- | テスト・運用手順・判断記録 | 検証、復旧操作、採否の正本。本書には対象フローとの対応と不足の影響を示す |
28
+ | 情報 | 本書との責務境界 |
29
+ | -------------------------- | ------------------------------------------------------------ |
30
+ | システム設計索引 | 実装・設定・定義ファイルの所在と共通条件の正本 |
31
+ | 業務フロー・状態遷移仕様 | 対象者・起動条件・状態用語の正本 |
32
+ | テスト・運用手順・判断記録 | 検証・復旧操作・採否の正本。フローとの対応と不足の影響を示す |
33
33
 
34
- - **永続化点**: 中断後も状態確定の証拠として参照する保存地点。要求を送っただけの地点と区別する。
35
- - **再実行性**: 同じ操作を繰り返した場合の結果と、その実行を許せる条件。冪等を保証しない経路も明示する。
36
- - **補償**: 部分成功後に取り消し、戻し、代替処理で整合を回復すること。履歴を消す操作とは区別する。
34
+ - **永続化点**: 中断後も状態確定の証拠となる保存地点。要求送信だけの地点と区別する。
35
+ - **再実行性**: 繰返し操作の結果と実行を許す条件。冪等を保証しない経路も示す。
36
+ - **補償**: 部分成功後の取消・戻し・代替処理による整合回復。履歴削除と区別する。
37
37
 
38
38
  ## 3. ファイル命名・ID規則
39
39
 
40
- - ファイルは `sysd-critical-flows.md` を基準とし、対象範囲のシステム設計文書群へ置く。
41
- - 文書 ID は対象リポジトリの名前空間規約に従う。フロー ID は `scf-001` 形式で一意にし、廃止した ID を別の意味へ再利用しない。
42
- - フロー名は成功後の結果が分かる表現にする。未決事項や検証条件にも文書内で一意な ID を付け、フロー ID と対応させる。
43
- - 統合・廃止時は ARC が図・一覧・設計索引を、DEV が実装・schema・CLI・互換性を、QE がテストを、OPS が運用導線を確認する。PM は計画・登録簿への影響を管理し、人間の PO が採否を承認する。
40
+ - ファイルは `sysd-critical-flows.md` を基準に、対象のシステム設計文書群へ置く。
41
+ - 文書 ID は適用先の名前空間に従う。フロー ID は `scf-001` 形式で一意とし、廃止 ID を再利用しない。
42
+ - フロー名は成功後の結果を表す。未決事項・検証条件にも文書内で一意な ID を付け、フロー ID と結ぶ。
44
43
 
45
44
  ## 4. 推奨 Frontmatter 項目
46
45
 
47
- 共通の形式・必須キー・型は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] と `docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml`(共通定義は `common-frontmatter.schema.yaml`)を正本とする。以下の項目は `specdojo:` 名前空間配下に置く。文書名は本文先頭の H1 に記し、`specdojo.title` は使用しない。
46
+ 共通の形式・必須キー・型は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] を正本とする。
48
47
 
49
- | 項目 | 必須性 | 本系統での判断・記入方針 |
50
- | ---------------------- | ------ | ---------------------------------------------------------------------------------------------- |
51
- | `id` | 必須 | 対象範囲で一意な文書 ID を示す |
52
- | `type` | 必須 | システム設計として `architecture` を使う |
53
- | `status` | 必須 | 文書の成熟度を示す。AI Agent は `ready` へ昇格させない |
54
- | `rulebook` | 必須 | 本規約の ID を示す |
55
- | `owner` | 任意 | 更新責任の Role code を示す。人間の最終承認者とは区別する |
56
- | `part_of` / `based_on` | 任意 | 所属索引と、実際に判断へ用いた依存範囲内の根拠を示す。参照ハブから辿れる文書を一律に転記しない |
48
+ - `type` は `architecture`、`rulebook` は本規約の ID とする。
49
+ - `part_of` は所属するシステム設計索引を示す。
50
+ - `based_on` は判断に用いた依存範囲内の根拠に限り、参照ハブの先を一律に転記しない。
57
51
 
58
52
  ## 5. 本文要件
59
53
 
60
- 全章を必須とする。見出し順・表・記入欄の骨組みは宣言された雛形を正本とし、ここでは意味要件を定める。
54
+ 全章必須。見出し順・表・記入欄は宣言された雛形、意味要件は以下を正本とする。
61
55
 
62
- | 内容 | 目的と満たす条件 |
63
- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
64
- | 概要 | 対象・対象外、最大5件の管理方針、設計索引への接続、公開する情報と除外する情報、人間の最終承認責任を示す |
65
- | 重要フロー一覧 | ID・名称・事故論点に、影響を受ける利用者/運用者、放置時の影響、期待効果、通常処理より優先する理由を対応させる |
66
- | フロー詳細 | フローごとに目的・トリガー・範囲・主要入出力、図、永続化点、整合性・冪等・再実行、失敗時の保持・補償・再開条件、利用者が確認できる受入条件を示す |
67
- | 観測性と運用連携 | フローごとの相関キーと追跡範囲、trace の伝搬範囲または非採用理由、監視条件・閾値の正本、実装動作、人間の一次対応とエスカレーション先を分離して示す |
68
- | 関連ドキュメント導線 | 実装・設定、テスト、運用、判断記録への一意な導線と変更影響を示す。未解決事項、依存順・担当・完了条件・判断時期、公開/承認条件もここで管理する |
56
+ | 内容 | 目的と満たす条件 |
57
+ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
58
+ | 概要 | 対象・対象外、最大5件の管理方針、設計索引への接続、公開する情報と除外する情報を示す |
59
+ | 重要フロー一覧 | ID・名称・事故論点に、影響を受ける利用者/運用者、放置時の影響、期待効果、通常処理より優先する理由を対応させる |
60
+ | フロー詳細 | フローごとに目的・トリガー・範囲・主要入出力、図、永続化点、整合性・冪等・再実行、失敗時の保持・補償・再開条件、利用者が確認できる受入条件を示す |
61
+ | 観測性と運用連携 | フローごとの相関キーと追跡範囲、trace の伝搬範囲または非採用理由、監視条件・閾値の正本、実装動作、人間の一次対応とエスカレーション先を分離して示す |
62
+ | 関連ドキュメント導線 | 実装・設定、テスト、運用、判断記録への一意な導線と、契約・schema・生成物・CLI・保存済み記録の互換性への変更影響を示す。未決事項は論点・依存・受入や運用への影響・当面の扱い・解消条件を示す |
69
63
 
70
- フロー詳細の図はシステム内外、サービス/プロセスと保存先の境界、主要識別子、同期・非同期の区別を示す。矢印の意味を定義し、要求受付と業務完了を同一視しない。分散トレースの導入は必須とせず、複数プロセスを関連付ける方法を示す。
64
+ 図はシステム内外・サービス/プロセス・保存先の境界、主要識別子、同期・非同期と矢印の意味を示し、要求受付と業務完了を分ける。分散トレースは必須とせず、プロセス間の相関方法を示す。
71
65
 
72
- テスト参照は実在するパスまたはテスト ID とし、実行方法、対象条件、期待結果、失敗判定を対応させる。既存テストの所在確認とシナリオ網羅の確認を区別し、未網羅なら担当と解消先を示す。内部結合テストは ITC(`itc-` 系)、外部結合テストは ETC(`etc-` 系)の名称を使う。
66
+ テスト参照は実在するパスまたはテスト ID とし、受入条件に実行方法・対象条件・期待結果・失敗判定を対応させる。所在・網羅性・実行結果を区別し、不足は未決事項に接続する。内部結合は ITC(`itc-` 系)、外部結合は ETC(`etc-` 系)とする。
73
67
 
74
68
  ## 6. 記述ガイド
75
69
 
76
- 共通の状態・権限・設定は上位の索引・仕様を正本とし、本書にはフロー固有の条件だけを書く。
77
-
78
70
  ### 6.1. 概要
79
71
 
80
- - 判断基準: 対象の入口・出口と最終承認責任が特定でき、公開範囲を判断できること。
81
- - 良い例: 「販売要求から受付照合までを扱う。公開版は設計条件だけを含み、顧客別の購入記録は含めない。実運用の採否は人間の PO が判断する」。
82
- - 悪い例: 「システム全体を安全に運用する」。境界と判断者が分からない。
72
+ - 判断基準: 対象の入口・出口と公開範囲が特定できること。
73
+ - 良い例: 「販売要求から受付照合まで。公開版は設計条件だけを含み、顧客別の購入記録は除く」。
74
+ - 悪い例: 「システム全体を安全に運用する」。境界が分からない。
83
75
 
84
76
  ### 6.2. 重要フロー一覧
85
77
 
86
- - 推奨列は ID、名称、事故論点、対象者、業務影響、期待効果・選定理由。優先度だけで選定理由の代わりにしない。
87
- - 判断基準: 重複実行や中断によって誰のどの作業が損なわれるかを説明でき、追加候補と既存フローの比較から対象を絞れていること。
88
- - 良い例: 「応答欠落後の売上再送は二重計上の恐れがあるため、閲覧より先に扱う」。
78
+ - 推奨列は ID、名称、事故論点、対象者、業務影響、期待効果・選定理由。優先度だけでは選定理由にならない。
79
+ - 判断基準: 重複・中断による対象者の損失で、追加候補と既存フローを比較できること。
80
+ - 良い例: 「応答欠落後の再送は二重売上になるため、閲覧より優先する」。
89
81
  - 悪い例: 「重要なので High」。他候補より優先する根拠がない。
90
82
 
91
83
  ### 6.3. フロー詳細
92
84
 
93
- - 判断基準: 任意の永続化点で止めても、残存状態と再開条件が一つに定まること。設定依存の上限はキーまたは一意な設計参照へ接続する。
94
- - 良い例: 「外部受付後に応答が失われた場合は取引 ID で照合し、未受付と確認するまで再送しない。受入では同一 ID の二回入力が一件の売上になることを確認する」。
85
+ - 判断基準: 各永続化点で中断後の残存状態・再開条件が一意に定まること。設定依存の上限はキーか一意な設計参照へ結ぶ。
86
+ - 良い例: 「受付後の応答欠落は取引 ID で照合し、未受付と確認するまで再送しない。受入では同一 ID の二回入力が売上一件になることを確認する」。
95
87
  - 悪い例: 「失敗なら retry」。受付済み、保存失敗、通信失敗を区別していない。
96
- - 図の良い例: 内部 CLI、端末保存、外部受付を境界で分け、同じ取引 ID を送信・受付・控えに対応させる。矢印の凡例から、送信と応答欠落後の照合を見分けられる。
97
- - 図の悪い例: 「受付 → 保存 → 完了」だけを並べる。保存主体・識別子・応答欠落時の経路が分からない。
88
+ - 図の良い例: CLI 内部・端末保存・外部受付を分け、同じ取引 ID で結ぶ。凡例で送信と応答欠落後の照合を区別する。
89
+ - 図の悪い例: 「受付 → 保存 → 完了」。保存主体・識別子・応答欠落時の経路が不明。
98
90
 
99
91
  ### 6.4. 観測性と運用連携
100
92
 
101
- - 判断基準: 検知条件、プログラムの動作、人間の対応、問い合わせ先、記録先が混ざっていないこと。閾値が未決なら無通知でよいとは判断しない。
102
- - 良い例: 「重複確定を一件検知したら自動処理を停止する設計。OPS が保持記録を確認して ARC へ照会し、PM へ issue 起票を依頼する」。
93
+ - 判断基準: 検知条件・実装動作・人間の対応・照会先・記録先を分けること。閾値未決を無通知でよいと扱わない。
94
+ - 良い例: 「重複確定一件で自動処理を停止。一次対応者が保持記録を確認して技術照会先へ渡す」。
103
95
  - 悪い例: 「runner が担当」。機械を責任者としている。
104
- - 相関の良い例: 「外部受付へ内部 trace を渡せないため、取引 ID と受付 ID で CLI・外部受付・保存控えを照合する」。全フロー共通の方針は一度だけ記し、フロー別のキーと範囲へ対応付ける。採否未確認なら代替手段と確認担当・解消先を示す。
105
- - 相関の悪い例: 「`trace_id` を記録する」。境界を越えた対応や保存先まで追えるか判断できない。
96
+ - 相関の良い例: 「内部 trace を渡せない外部受付は、取引 ID と受付 ID で CLI・保存控えと照合する」。共通方針は一度だけ記し、フロー別のキー・範囲へ結ぶ。採否未確認なら代替手段と確認条件を示す。
97
+ - 相関の悪い例: 「`trace_id` を記録する」。境界から保存先まで追えるか不明。
106
98
 
107
99
  ### 6.5. 関連ドキュメント導線
108
100
 
109
- - 判断基準: 読み手が同じ正本・検証・未決事項へ辿れ、未作成の手順と確認済みの参照を見分けられること。
110
- - 良い例: 「検証 V-01 は指定したテストファイルを実行し、二重反映を fail とする。未作成の障害手順は U-01 で OPS が追跡し、受入前に PM が Schedule へ依存を登録する」。
111
- - 悪い例: 「関連テスト、障害対応 OPR を参照」。所在・成立条件・未整備の影響が分からない。
101
+ - 判断基準: 正本・検証・未決事項へ辿れ、未作成の手順と確認済みの参照を見分けられること。
102
+ - 良い例: 「V-01 は指定テストで二重反映を fail とする。U-01 の照合手順が未整備なら、受付不明時の自動再送を保留する」。
103
+ - 悪い例: 「テスト、OPR を参照」。所在・成立条件・未整備の影響が不明。
112
104
 
113
105
  ## 7. 禁止事項
114
106
 
115
107
  - 総数6件以上のフローを掲載すること、全 API や通常処理を網羅すること。
116
- - 設定値・構文・schema の表、実装の逐語説明、図をなぞるだけの本文を二重管理すること。
117
108
  - 保存前に完了扱いすること、根拠のない retry・補償・自動再開を指示すること。
118
- - 一般名称や glob だけで参照を済ませること、未作成文書を存在するリンクとして記載すること。
119
- - テストファイルの存在を、シナリオ網羅・実行成功・人間承認の証拠として扱うこと。
120
- - 未決事項の影響・担当・解消条件を省くこと、機械の動作主体と人間の責任を混同すること。
109
+ - 一般名称や glob だけで実装・設定・テスト・復旧手順の参照を済ませること。
110
+ - テストファイルの存在を、シナリオ網羅・実行成功の証拠として扱うこと。
111
+ - 未決事項の影響・当面の扱い・解消条件を省くこと、機械の動作主体と人間の一次対応を混同すること。
@@ -13,105 +13,101 @@ specdojo:
13
13
 
14
14
  System Design Cross-cutting Policy Documentation Rules
15
15
 
16
- 複数の実装領域で守る制約、例外、検証条件を一つの正本にまとめるための規定である。値・構文・構造の詳細は実装・schema・リファレンスに委ね、共通の判断と適用境界を定める。
16
+ 複数の実装領域で守る制約、例外、検証条件を一つの正本にまとめるための規定である。値・構文・構造の詳細は実装・schema・リファレンスに委ねる。
17
17
 
18
18
  ## 1. 全体方針
19
19
 
20
- - 対象システムの複数モジュールに共通する必須・禁止条件を扱う。個別機能の詳細手順や一時作業の計画は持ち込まない。
21
- - 対象者の課題と上位の価値・成功基準への寄与を短く示す。プロジェクト背景の全文を再掲しない。
22
- - 各ルールを入力条件と観測可能な期待結果で判定できるようにする。規定の存在と実装済みの証拠を区別する。
23
- - 未確定の値や業務判断を推測しない。担当、判断期限、影響、次アクションを伴う共通ラベルで残す。
20
+ - 複数モジュールに共通する必須・禁止条件を扱い、個別機能の手順や一時作業の計画は持ち込まない。
21
+ - 各ルールを入力条件と観測可能な期待結果で判定できるようにし、規定の存在と実装済みの証拠を区別する。未確定の値は推測しない。
22
+ - **共通の運用**: 役割の割り当ては適用先のメンバー定義に、`status` の昇格と承認、文書の改訂と廃止、未決事項の登録簿への引き継ぎは [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従い、本書と成果物で言い直さない。文書の整形・lint はリポジトリの検証で扱い、ルールの適合確認に含めない。
24
23
 
25
24
  ## 2. 位置づけと用語定義
26
25
 
27
- | 情報 | 責務 |
28
- | -------------------------- | -------------------------------------------------------- |
29
- | システム設計索引 | 実装・設定・schema・生成物の所在と変更の入口 |
30
- | 横断ルール | 複数領域に共通する不変条件、適用範囲、例外、検証の正本 |
31
- | 個別設計・非機能要件・運用 | 個別の構成、目標値、通知・保持・回復手順の詳細 |
32
- | 決定記録・登録簿・Schedule | 例外承認、課題・リスク・変更、担当・期限・作業進捗の正本 |
26
+ | 情報 | 責務 |
27
+ | -------------------------- | ------------------------------------------------------ |
28
+ | システム設計索引 | 実装・設定・schema・生成物の所在と変更の入口 |
29
+ | 横断ルール | 複数領域に共通する不変条件、適用範囲、例外、検証の正本 |
30
+ | 個別設計・非機能要件・運用 | 個別の構成、目標値、通知・保持・回復手順の詳細 |
31
+ | 決定記録・登録簿 | 例外承認、課題・リスク・変更の正本 |
33
32
 
34
- 「例外」は通常規則から承認を得て外れる条件、「不適合」は未承認の逸脱、「未確認」は適合証拠が未取得の状態とする。未確認を例外や実装済みへ読み替えない。
33
+ 「例外」は承認を得て通常規則から外れる条件、「不適合」は未承認の逸脱、「未確認」は適合証拠が未取得の状態とする。未確認を例外や実装済みへ読み替えない。
35
34
 
36
35
  ## 3. ファイル命名・ID規則
37
36
 
38
- - ファイル名は `sysd-cross-cutting-policy.md` を基本とし、文書 ID の authority はプロジェクトの共通命名規約に従う。
39
- - ルール ID は `scp-<カテゴリ>-<連番>` とし、同じ適用範囲内で一意かつ改訂後も追跡可能にする。
37
+ - ファイル名は `sysd-cross-cutting-policy.md` を基本とする。
38
+ - ルール ID は `scp-<カテゴリ>-<連番>` とし、同じ適用範囲内で一意にする。
40
39
  - カテゴリは `ERR`(エラー)、`IDM`(冪等)、`TIM`(時間制御)、`RET`(再試行)、`LOG`(ログ)、`TRC`(追跡)、`SEC`(保護)、`CFG`(設定)、`MOD`(境界)等を使う。カテゴリ追加で必須領域を隠さない。
40
+ - 置き換え・廃止した Rule ID は再利用せず、ルール一覧に後継 Rule ID または廃止理由を残す。その Rule の Owner が、「関連導線」の変更影響に挙げた参照先(システム設計索引・実装・テスト・運用文書)と検証の対応の更新を確かめる。
41
41
 
42
42
  ## 4. 推奨 Frontmatter 項目
43
43
 
44
- - 共通の型・許容値は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] と成果物 Frontmatter schema を正とし、ここで再定義しない。
45
- - 成果物・完成例と template の生成物 Frontmatter では、`type` を本書の `deliverable_type` と同じ `architecture` に、`rulebook` を本書の完全 ID にする。template 自身の `type: template` と混同しない。設計索引へ所属する成果物は `part_of` で接続する。
46
- - `based_on` は実際に判断に使った依存範囲内の文書だけにする。プロジェクト共通文脈を機械的に転記しない。
47
- - `status` は agent が `ready` に変更しない。公開可否と昇格の判断責任は本文にも示す。
44
+ - 共通の型・許容値は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] と成果物 Frontmatter schema を正とする。
45
+ - `type` は `architecture`、`rulebook` は `specdojo:sysd-cross-cutting-policy-rulebook` とし、設計索引へは `part_of` で接続する。`based_on` は判断に使った依存範囲内の文書だけにする。
48
46
 
49
47
  ## 5. 本文要件
50
48
 
51
- 見出し順・表・記入欄の骨組みは frontmatter で宣言する template を正とし、ここでは意味要件を定める。Markdown の `##`〜`####` には階層ごとの連番と末尾の `.` を付ける。
49
+ 見出し順・表の骨組みは template を正とし、ここでは意味要件を定める。
52
50
 
53
- | 内容 | 必須 | 意味・判定に必要な情報 |
54
- | ------------------ | ---- | ------------------------------------------------------------------------------------------------------------------------------- |
55
- | 概要 | ○ | 対象・対象外、競合時の優先判断、上位価値への寄与、利用者・確認者・人間の最終承認者 |
56
- | ルール一覧 | ○ | ID・カテゴリ・要約・必須度・Owner。全詳細と対応し、実装状況または確認待ち、確認時機と依存順へ接続 |
57
- | 各ルール詳細 | ○ | Rule、Rationale、Scope、Enforcement、Exception、References の六要素。条件・期待結果・正本・検証コマンドを特定 |
58
- | 例外 | ○ | 承認済み例外の有無、対象 Rule ID・理由・影響・期限・判断者・復帰条件・決定参照。不適合・risk・change・decision の記録と追跡責務 |
59
- | 関連導線 | ○ | 設計、非機能、運用、テスト、判断記録への入口。Rule 変更から schema・生成物・互換性・移行・回帰対象への影響と担当 |
60
- | 未決事項・公開条件 | ○ | 未確定の対象 ID、判断者・期限・影響・次アクション、計画登録の状況。確認完了と人間による公開・昇格の条件 |
51
+ | 内容 | 必須 | 意味・判定に必要な情報 |
52
+ | ------------------ | ---- | ----------------------------------------------------------------------------------------------- |
53
+ | 概要 | ○ | 対象・対象外、競合時の優先判断、上位価値への寄与、誰がどの判断に使うか |
54
+ | ルール一覧 | ○ | ID・カテゴリ・要約・必須度・Owner。全詳細と対応し、実装状況または確認待ちと確認時機へ接続 |
55
+ | 各ルール詳細 | ○ | Rule、Rationale、Scope、Enforcement、Exception、References の六要素。条件・期待結果・正本・検証 |
56
+ | 例外 | ○ | 承認済み例外の対象 Rule ID・理由・影響・期限・判断者・復帰条件・決定参照。不適合との区別 |
57
+ | 関連導線 | ○ | 設計、非機能、運用、テスト、判断記録への入口。Rule 変更から schema・互換性・移行・回帰への影響 |
58
+ | 未決事項・公開条件 | ○ | 未確定の対象 Rule ID、論点と影響(当面の扱い)。実装の根拠にする前に済ませる適合確認 |
61
59
 
62
- - 完成例にも上表の必須内容とルール詳細の六要素を適用する。架空の正本・検証コマンドは未同梱と明示し、検証計画を実行済み証跡として扱わない。
63
- - 共通エラー・冪等・時間上限と打切り・retry・診断ログと監査・トレーシング・秘密と権限・設定上書き・モジュール境界を必ず検討する。非該当は構成上の理由と代替手段、または代替不要の理由を示す。
64
- - HTTP API がなければ CLI 等のエラー契約を扱い、DB がなければファイル保存と途中状態の整合性を扱う。特定技術がないことを領域全体の対象外理由にしない。
65
- - retry は冪等前提、signal 分類、回数の数え方、attempt・backoff 上限、fallback・上限到達時の処置を正本の値または設定キーへ接続する。未定義なら受入を保留し、判断課題を明示する。
66
- - timeout は経路別の設定・単位、終了対象、部分出力・保存状態、再開条件を結ぶ。ログ・監視は相関、秘匿化、保持、検知・通知・一次対応の適用範囲を示す。
60
+ - 共通エラー・冪等・時間上限と打切り・retry・診断ログと監査・トレーシング・秘密と権限・設定上書き・モジュール境界を必ず検討する。非該当は理由と代替手段(または代替不要の理由)を示す。
61
+ - HTTP API がなければ CLI 等のエラー契約、DB がなければファイル保存と途中状態の整合性を扱う。特定技術の不在を領域全体の対象外理由にしない。
62
+ - retry は冪等前提、signal 分類、回数の数え方、attempt・backoff 上限、上限到達時の処置を正本の値または設定キーへ接続する。未定義なら受入を保留する。
63
+ - timeout は経路別の設定・単位、終了対象、部分出力・保存状態、再開条件を結ぶ。ログ・監視は相関、秘匿化、保持、検知・通知・一次対応の範囲を示す。
64
+ - 完成例では架空の正本・検証コマンドを未同梱と明示し、検証計画を実行済み証跡として扱わない。
67
65
 
68
66
  ## 6. 記述ガイド
69
67
 
70
- 共通の値・構造・用語は上位索引または各正本へ委ねる。以下の例は局所的な判断例であり、完成例を本文へ埋め込まない。
68
+ 以下は局所的な判断例であり、完成例は sample を参照する。
71
69
 
72
70
  ### 6.1. 概要
73
71
 
74
- 判断基準は、読む人が対象と適用しない境界、競合時の判断、人間の承認責務を説明できることである。
72
+ 判断基準は、読む人が対象と適用しない境界、競合時の判断を説明できることである。
75
73
 
76
- - 良い例: 「CLI と日次処理を対象にし、無限再試行を防いで参加者の復旧負荷を減らす。DEV が実装、QE / OPS が確認し、人間の PO が公開可否を判断する」。
77
- - 悪い例: 「全体に適切な規則を適用する」。対象と責任が判断できない。
74
+ - 良い例: 「CLI と日次処理を対象にし、無限再試行を防いで参加者の復旧負荷を減らす。外部連携の契約と競合した場合は契約を優先する」。
75
+ - 悪い例: 「全体に適切な規則を適用する」。対象と境界が判断できない。
78
76
 
79
77
  ### 6.2. ルール一覧
80
78
 
81
- 判断基準は、一覧・詳細・適合確認の Rule ID が相互に対応し、要約と必須度の組合せで要求・禁止が同じ意味になることである。推奨列は `Rule ID / Category / Summary / Level / Owner` とする。適合状況、依存、確認時機は別の対応表へ分けてもよい。作業の進捗を本文で二重管理しない。
79
+ 判断基準は、一覧・詳細・適合確認の Rule ID が対応し、要約と必須度の組合せで要求・禁止が同じ意味になることである。推奨列は `Rule ID / Category / Summary / Level / Owner` とし、適合状況・確認時機は別表へ分けてもよい。作業の進捗は本文で二重管理しない。
82
80
 
83
81
  - 良い例: 「`scp-CFG-001`、不正設定で起動しない、MUST、DEV、実装未照合、起動前に V2 で確認」。
84
- - 悪い例: 「設定責務を分離する、MUST NOT」。必須度を組み合わせると意図と逆になり、進捗にも展開できない。
82
+ - 悪い例: 「設定責務を分離する、MUST NOT」。必須度を組み合わせると意図と逆になる。
85
83
 
86
84
  ### 6.3. 各ルール詳細
87
85
 
88
- 判断基準は、条件が同じなら期待動作と合否が一意になり、検証する正本へ到達できることである。共通の検証群へ束ねる場合も Rule ID との対応を残す。
86
+ 判断基準は、条件が同じなら期待動作と合否が一意になり、検証する正本へ到達できることである。Rule は不変条件に絞り、検証の入口は Enforcement、低レベル手順は実装・運用正本に置く。
89
87
 
90
- - 良い例: 「再送は保存済みの受付結果を照合した後だけ許可する。応答欠落では結果不明を保持し、自動再送しない。設定キーは契約正本、回帰対象と実行コマンドは検証表へ接続する」。
88
+ - 良い例: 「再送は保存済みの受付結果を照合した後だけ許可する。応答欠落では結果不明を保持し、自動再送しない。回帰対象と実行コマンドは検証表へ接続する」。
91
89
  - 悪い例: 「criticality に応じて retry」。区分・signal 対応・上限の正本がなく判断不能。
92
- - Rule は不変条件に絞る。検証の入口を Enforcement、低レベル手順を実装・運用正本に集約し、同じ内容を Scope に繰り返さない。
93
90
 
94
91
  ### 6.4. 例外
95
92
 
96
93
  判断基準は、通常ルールへ復帰でき、未承認の不適合と承認済みの逸脱を区別できることである。
97
94
 
98
- - 良い例: 「依存の暫定許可は対象 adapter のみ、移行完了日まで、PO の decision と復帰条件を記録。違反は issue として DEV が報告、PM が追跡する」。
99
- - 悪い例: 「緊急時は担当判断で無期限に解除」。影響・期限・責任が追跡できない。
95
+ - 良い例: 「依存の暫定許可は対象 adapter のみ、移行完了日まで、decision と復帰条件を記録。違反は issue として報告する」。
96
+ - 悪い例: 「緊急時は担当判断で無期限に解除」。影響・期限・復帰が追跡できない。
100
97
 
101
98
  ### 6.5. 関連導線
102
99
 
103
- 判断基準は、読み手が参照目的を理解して現行正本へ進め、変更時の追従先を選べることである。見出し・表・リンクでは参照先の文書名を基準に呼称を揃え、略号を使う場合は対応する文書名を示す。
100
+ 判断基準は、読み手が現行正本へ進み、変更時の追従先を選べることである。呼称は参照先の文書名に揃える。
104
101
 
105
- - 良い例: 「保存形式変更は DEV が schema と移行を同期し、旧形式・再実行の回帰を確認。運用索引は未作成のため OPS が整備後に接続する」。
102
+ - 良い例: 「保存形式変更は schema と移行を同期し、旧形式・再実行の回帰を確認する。運用索引は未作成のため整備後に接続する」。
106
103
  - 悪い例: 「provider 別設計、運用一式、旧フロー参照」。実在する ID・相対パスがなく特定できない。
107
- - 呼称の良い例: 「システム設計索引」「重要フロー」を表と参照ラベルで揃える。悪い例: 同じ参照先を表では「SYSD Critical Flows」、導線では説明なく「SYSD-CF」と呼び分ける。
108
104
 
109
105
  ### 6.6. 未決事項と公開条件
110
106
 
111
- 判断基準は、PO が承認・保留・差し戻しを選べることである。未発行の作業 ID を発行済みとみなさない。
107
+ 判断基準は、未決の論点がどの Rule ID の受入を止めるかと当面の扱いが分かることである。未発行の作業 ID を発行済みとみなさない。
112
108
 
113
- - 良い例: 「通知先は未決。OPS が公開前に設計し、PM が issue と Schedule へ接続、QE が失敗注入で確認、PO が期限付き留保の可否を判断する」。
114
- - 悪い例: 「NFR / OPD は後続で接続する」。誰がいつ何を判断するか分からない。
109
+ - 良い例: 「`_UNDECIDED_`: 通知先。決まるまで `scp-LOG-001` の検知・通知は未確認とし、失敗注入での確認を受入の前提に残す」。
110
+ - 悪い例: 「NFR / OPD は後続で接続する」。何が未決でどのルールに効くか分からない。
115
111
 
116
112
  ## 7. 禁止事項
117
113
 
@@ -122,4 +118,4 @@ System Design Cross-cutting Policy Documentation Rules
122
118
  | 非該当と未整備を混同し必須領域を消す | 障害・回復・観測の責務が欠ける |
123
119
  | 検査名だけで入力・期待結果・実行経路を示さない | 合否を再現できない |
124
120
  | 例外を散在させ、期限・判断・復帰を省く | 通常規則へ戻せない |
125
- | agent に公開・昇格の最終判断を委ねる | 人間の説明責任を失う |
121
+ | 置き換え・廃止した Rule ID を再利用する、後継を示さない | 実装・テストの参照が追えない |
@@ -16,115 +16,90 @@ specdojo:
16
16
 
17
17
  System Design Index Documentation Rules
18
18
 
19
- システム設計の正本、派生物、変更時の更新先への導線を集約する索引の規約を定める。値・構文・構造の詳細はコード、schema、リファレンスを正本とし、索引では所在と責任、変更影響、確認経路を扱う。
19
+ システム設計の正本、派生物、変更時の更新先への導線を集約する索引の規約を定める。
20
20
 
21
21
  ## 1. 全体方針
22
22
 
23
23
  - 合意したシステム範囲につき、設計情報の入口を一つにする。全依存ファイルの台帳にはしない。
24
- - 公開インターフェース、データ保存・移行、設定、実行構成、運用・監視の正本へ到達できるようにする。
25
- - 未記載と非該当を区別する。非該当には理由と代替正本、未確認には担当と確認条件を付ける。
26
- - 正本と生成物を分け、生成コマンド、出力先、閲覧方法を対応付ける。生成物を直接編集しない。
27
- - 変更目的から更新先、追従対象、検証対象と期待結果を逆引きできるようにする。
28
- - 人間が構成判断と公開を承認する。未決事項の解消や `ready` 昇格をエージェントが代行しない。
29
-
30
- ## 2. 位置づけと用語定義
31
-
32
- | 用語・情報 | この索引での役割 |
33
- | --------------------------------------- | -------------------------------------------------------------------------------------------------------- |
34
- | SSOT(Single Source of Truth、正本) | 各設計要素を最初に更新・参照する一次情報。コード・定義ファイルを仕様として扱う運用を Code as Spec と呼ぶ |
35
- | システム設計(System Design、SYSD)索引 | 正本の所在と変更経路をつなぐ入口。詳細な設計判断は分冊へ委ねる |
36
- | 技術スタック・構成図 | 採用技術や境界を理解するための上位・隣接情報。索引では参照目的を示す |
37
- | 自動生成物 | 正本を入力とする型、索引、閲覧ページ、配布物などの派生物 |
38
- | 運用・テスト仕様 | 変更後の検証と運用判断の入力。索引では対象ケースと手順への入口を示す |
24
+ - 存在しない領域も残し、非該当には理由と代替正本(または代替不要の理由)、未確認には論点と影響を示す。
25
+ - 正本と生成物を分け、生成物を直接編集しない。
26
+ - **共通の運用**: 役割の割り当ては適用先のメンバー定義に、`status`・承認・改訂と廃止・未決事項の引き継ぎは [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従う。文書の整形・lint はリポジトリの検証で扱い、業務の受入確認に含めない。
27
+
28
+ ## 2. 位置づけ
29
+
30
+ システム設計(System Design、SYSD)索引は、正本(SSOT: Single Source of Truth)の所在と変更経路をつなぐ入口である。詳細な設計判断は分冊、変更後の確認は運用・テスト仕様が担う。
39
31
 
40
32
  ## 3. ファイル命名・ID規則
41
33
 
42
34
  - ファイル名は `sysd-index.md` とし、対象のシステム設計文書群に置く。
43
- - ID は対象範囲で一意な `sysd-index` 系とする。名前空間・配置は [[specdojo:id-and-file-naming-standard|ID・ファイル命名標準]] に従う。
44
- - H1 にはシステム名と索引であることを示す。分冊を追加しても索引の正本を複製しない。
35
+ - ID は対象範囲で一意な `sysd-index` 系とし、名前空間・配置は [[specdojo:id-and-file-naming-standard|ID・ファイル命名標準]] に従う。
36
+ - H1 にはシステム名と索引であることを示す。
45
37
 
46
38
  ## 4. 推奨 Frontmatter 項目
47
39
 
48
- 共通の型・許可項目は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] と `docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml` を正とする。タイトルは H1 に記載し、schema が許可しない `specdojo.title` を追加しない。
40
+ 共通の型・許可項目は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] と `docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml` を正とする。
49
41
 
50
- | 項目 | 扱い | 索引での記述判断 |
51
- | ------------------------ | -------- | -------------------------------------------------------------------------------- |
52
- | `id` / `type` / `status` | 必須 | 一意な ID、`architecture`、現在の成熟度を記す。作成・編集時は `draft` を維持する |
53
- | `rulebook` | 必須 | 本規約の完全 ID を宣言する |
54
- | `part_of` | 任意 | 所属する上位文書がある場合にだけ指定する |
55
- | `based_on` | 条件付き | 許可された依存関係内の直接根拠だけを指定する。関連リンクを転記しない |
56
- | `supersedes` | 条件付き | 旧索引を置き換える場合に指定する |
42
+ - `type` は `architecture`、`rulebook` は `specdojo:sysd-index-rulebook` とする。
43
+ - `based_on` は直接の根拠だけを指定し、関連リンクを転記しない。
57
44
 
58
45
  ## 5. 本文要件
59
46
 
60
- 見出し順・表の列・記入欄は Frontmatter で宣言した template を正本とし、本章は内容の成立条件を定める。`##`〜`####` は階層ごとの連番と末尾の `.` を付ける。
47
+ 見出し順・表の列は template を正本とし、本章は内容の成立条件を定める。
61
48
 
62
- | 内容領域 | 必須・任意 | 成立条件 |
63
- | -------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
64
- | 対象と責任 | 必須 | 対象範囲、更新責任、QE の確認対象、人間の承認対象が分かる。使う略語は初出時に展開するか用語への導線を置く |
65
- | 設計正本 | 必須 | API・外部連携、データ契約・DB・移行、モジュール境界、設定・実行構成、Job・定期処理、監視・ログ・通知、ソース管理・CI の所在、更新責任、検証方法を示す |
66
- | 派生物 | 必須 | 入力、実在する生成コマンド、生成先、閲覧先・再生成時機を対応付ける。生成しない場合はその理由を記す |
67
- | 変更経路 | 必須 | API・DB・設定・Job・監視などの変更トリガーから、最初の更新先、追従する文書・生成物、具体的検査・ケース・期待結果へつながる |
68
- | 関連仕様 | 必須 | 上位・同階層・下流の参照目的と整備状態が分かる。実在文書と未作成文書を区別する |
69
- | 留保と公開判断 | 条件付き必須 | `draft`、未決・未整備事項、公開判断のいずれかがある場合、影響、担当、解消条件、解消後の更新先、確認者・承認者を示す |
49
+ | 内容領域 | 必須・任意 | 成立条件 |
50
+ | ---------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
51
+ | 対象と責任 | 必須 | 対象範囲と対象外、利用者と利用目的が分かる。略語は初出時に展開する |
52
+ | 設計正本 | 必須 | API・外部連携、データ契約・DB・移行、モジュール境界、設定・実行構成、Job・定期処理、監視・ログ・通知、ソース管理・CI の所在、更新責任、検証方法を示す |
53
+ | 派生物 | 必須 | 入力、実在する生成コマンド、生成先、閲覧先・再生成時機を対応付ける。生成しない場合は理由を記す |
54
+ | 変更経路 | 必須 | 変更トリガーから、最初の更新先、追従する文書・生成物、検査・ケース・期待結果へつながる |
55
+ | 関連仕様 | 必須 | 上位・同階層・下流の参照目的と整備状態が分かる。実在文書と未作成文書を区別する |
56
+ | 留保事項 | 条件付き必須 | 未決・未整備の設計事項がある場合、論点、影響、当面の扱い、解消条件と解消後の更新先を示す |
70
57
 
71
- - API・DB・監視などが存在しない場合も該当領域を残し、非該当理由と代替正本または代替不要の理由を記す。
72
- - パスは基準ディレクトリを明示し、glob を用いる場合は集合を特定できる範囲にする。候補のパスを実在する正本として扱わない。
73
- - 値、API 電文、SQL、設定キー全量、クラス構造、詳細運用手順は転載しない。
58
+ - パスは基準ディレクトリを明示し、glob は集合を特定できる範囲にする。
74
59
 
75
60
  ## 6. 記述ガイド
76
61
 
77
- 共通の記法・メタ情報は上位標準を正本とし、各章では次の判断に集中する。
78
-
79
62
  ### 6.1. 概要の書き方
80
63
 
81
- 対象範囲と対象外、更新者、確認者、承認者を分ける。全ロールを機械的に列挙せず、兼務があれば責務の違いを残す。
82
-
83
- - 良い例: 「対象はローカル CLI と日次処理。DEV が定義を更新し、QE が変更ケースを確認、PO が保存範囲と公開を承認する。」
84
- - 悪い例: 「システム全体を扱い、担当者が適宜確認する。」対象と責任の境界がない。
64
+ - 良い例: 「開発担当が CLI と日次処理の保存形式を変更するときに使う。店舗端末のハードウェア設計は対象外。」
65
+ - 悪い例: 「システム全体を扱い、担当者が適宜確認する。」利用目的と対象境界がない。
85
66
 
86
67
  ### 6.2. SSOT 一覧の書き方
87
68
 
88
- 「種別」は設計領域、「正本」は最初に更新する定義、「参照先」はその所在、「更新責任」は担当ロール、「検証方法」は変更後の確認手段を記す。ログの出力ディレクトリと、ログ形式・出力・通知を決める設定を区別する。ソース管理・CI はブランチや統合の規約、ワークフロー・フック・検査 script の正本へ接続し、設定全文は転載しない。
69
+ 「正本」は最初に更新する定義を記す。ログは出力ディレクトリと、形式・通知を決める設定を区別する。ソース管理・CI は統合の規約、ワークフロー・フック・検査 script の正本へ接続する。
89
70
 
90
71
  - 良い例: 「DB は非該当(ファイル保存のみ)。正本は保存レコード schema と移行処理。DEV が更新し、既存形式の読込テストで検証する。」
91
- - 悪い例: 「DB はなし」「監視は運用文書を参照」。理由、代替正本、具体的な設定が分からない。
72
+ - 悪い例: 「DB はなし」。理由と代替正本が分からない。
92
73
 
93
74
  ### 6.3. 自動生成物の書き方
94
75
 
95
- 対象リポジトリの script・サブコマンド定義と出力先を照合する。一括コマンドと個別コマンドがある場合は役割を示し、同じ出力を別の正本にしない。業務記録や実行状態は、設計の正本から再生成する派生物と分ける。
76
+ 対象リポジトリの script 定義と出力先を照合し、同じ出力を別の正本にしない。業務記録や実行状態は派生物と分ける。
96
77
 
97
78
  - 良い例: 「API 定義から型を生成する script と出力ファイルを示し、API 変更時に再生成してビルドで整合を確かめる。」
98
- - 悪い例: 「ビルドすれば更新される」。入力・出力・実行方法が対応しない。
79
+ - 悪い例: 「ビルドすれば更新される」。入力と出力が対応しない。
99
80
 
100
81
  ### 6.4. 変更の入口の書き方
101
82
 
102
- 正常系に加え、変更が壊しやすい失敗・境界ケースを選ぶ。実行場所、検査コマンド、対象テストファイルまたはケース、期待結果を特定する。これから行う検証と実行済みの証跡を混同しない。
83
+ 正常系に加え、変更が壊しやすい失敗・境界ケースを選ぶ。これから行う検証と実行済みの証跡を混同しない。
103
84
 
104
- - 良い例: 「保存形式変更時は schema と移行処理を更新し、移行テストで旧形式の読込成功と再実行時の重複なしを確認する。検査の終了コードは `0`。」
105
- - 悪い例: 「代表実行で経路と分離を確認する」。対象、操作、期待結果が未定義である。
85
+ - 良い例: 「保存形式変更時は schema と移行処理を更新し、移行テストで旧形式の読込成功と再実行時の重複なしを確認する。」
86
+ - 悪い例: 「代表実行で経路と分離を確認する」。対象と期待結果がない。
106
87
 
107
88
  ### 6.5. 関連ドキュメント導線の書き方
108
89
 
109
- 実在する現行文書は `[[id|title]]`、表では `[[id\|title]]` で接続する。未作成文書はコード表記にして代替参照先と後続作業を記す。廃止済み ID は後継へ置き換える。
110
-
111
- 区分は文書の役割を示す名称で統一し、略語を使う場合は概要で展開した表記と揃える。C4 / NFR / OPD / DEC 等の略号だけを必須の分類にせず、対象の文書体系に合わせる。表の途中に空行を挟まず、各行を同じ列構成で記す。
112
-
113
- - 良い例: 「非機能要件(NFR)」「運用方針・手順(OPD / OPR)」で分類し、未作成の運用索引は ID と整備担当、当面使う個別手順を示す。
114
- - 悪い例: 同じ非機能要件を「品質」「NFR」と呼び分け、「関連: 旧フロー、運用一式」とだけ記す。区分の対応と現行・未整備の違いが分からない。
90
+ 区分は文書の役割を示す名称で統一する。C4 / NFR / OPD / DEC 等の略号だけを必須の分類にせず、対象の文書体系に合わせる。未作成文書には当面の代替参照先を示す。
115
91
 
116
- ### 6.6. 未決事項・公開前確認の書き方
92
+ - 良い例: 「非機能要件(NFR)」「運用方針・手順(OPD / OPR)」で分類し、未作成の運用索引は当面使う個別手順を示す。
93
+ - 悪い例: 同じ非機能要件を「品質」「NFR」と呼び分ける。
117
94
 
118
- 不明なものは _TODO_:、意思決定待ちは _UNDECIDED_:、仮置き前提は _ASSUMPTION_: として分ける。未決事項に影響範囲、担当、判断時機、次アクションを付ける。
95
+ ### 6.6. 留保事項の書き方
119
96
 
120
- - 良い例: 「通知先は未決。OPS が障害検知要件を確認し、公開前に PO が留保可否を判断する。決定後に設定正本と監視手順への導線を更新する。」
121
- - 悪い例: 「今後検討」。承認待ちの対象と解消条件が分からない。
97
+ - 良い例: 「通知先が未決で外部通知の疎通を検証できない。当面は実行ログを確認する。検知要件と通知先の決定後、設定正本と監視手順への導線を更新する。」
98
+ - 悪い例: 「今後検討」。影響と解消条件が分からない。
122
99
 
123
100
  ## 7. 禁止事項
124
101
 
125
- - 詳細定義を正本から転載し、索引を第二の仕様書にする。
102
+ - 値、API 電文、SQL、設定キー全量、クラス構造、詳細運用手順を正本から転載し、索引を第二の仕様書にする。
126
103
  - 非該当と未確認を同一視し、調べていない領域を無言で省略する。
127
104
  - 未作成・廃止済みの文書や存在しないコマンドを現行の導線として示す。
128
- - 完成例を本書へ埋め込む、または sample / recipe / template の本文リンク章を作る。対応関係は Frontmatter だけで宣言する。
129
105
  - 対象システムの実例にある製品、ファイル配置、ロール兼務を全案件の必須構成にする。
130
- - 改訂・廃止時に参照元への影響を放置する。[[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従い、ARC は設計導線、DEV は実装・schema・生成物、OPS は監視・手順、QE は検証入力を追従させ、PM が後続作業、人間の PO が公開判断を管理する。