specdojo 0.7.0 → 0.9.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 (462) hide show
  1. package/.github/agents/specdojo-orchestrator.md +7 -3
  2. package/CHANGELOG.md +217 -0
  3. package/dist/catalog/build.js +24 -1
  4. package/dist/catalog/catalog.js +16 -14
  5. package/dist/catalog/plan.js +1 -1
  6. package/dist/catalog/scaffold.js +4 -1
  7. package/dist/commands/agent.js +5 -3
  8. package/dist/commands/build.js +69 -10
  9. package/dist/commands/git.js +206 -0
  10. package/dist/commands/init.js +9 -3
  11. package/dist/commands/night-orchestrator.js +6 -4
  12. package/dist/commands/where.js +25 -0
  13. package/dist/dashboard/dashboard-timeline.js +18 -16
  14. package/dist/dashboard/dashboard.js +616 -261
  15. package/dist/dashboard/epic-plan.js +81 -0
  16. package/dist/dashboard/exec-records.js +16 -20
  17. package/dist/dashboard/routines.js +11 -12
  18. package/dist/dashboard/timeline-build.js +5 -9
  19. package/dist/dashboard/timeline.js +23 -18
  20. package/dist/devcontainer/scaffold.js +18 -0
  21. package/dist/docs/frontmatter-namespace.js +1 -48
  22. package/dist/docs/index-command.js +2 -2
  23. package/dist/docs/yaml-business-tables.js +243 -0
  24. package/dist/docs/yaml-interface-tables.js +106 -0
  25. package/dist/docs/yaml-pages-command.js +5 -3
  26. package/dist/docs/yaml-pages.js +268 -3
  27. package/dist/docs/yaml-table-shared.js +70 -0
  28. package/dist/docs/yaml-tables.js +39 -0
  29. package/dist/exec/agent-config.js +31 -0
  30. package/dist/exec/agent-plan.js +3 -2
  31. package/dist/exec/agent-protected-config.js +2 -0
  32. package/dist/exec/commands.js +100 -39
  33. package/dist/exec/commit-hook-skips.js +78 -0
  34. package/dist/exec/core.js +19 -7
  35. package/dist/exec/events.js +179 -8
  36. package/dist/exec/evidence.js +77 -19
  37. package/dist/exec/handoff.js +9 -13
  38. package/dist/exec/limit.js +1 -1
  39. package/dist/exec/mechanical-result.js +45 -0
  40. package/dist/exec/migrate-records.js +249 -0
  41. package/dist/exec/parent-validation.js +209 -15
  42. package/dist/exec/pipeline-state.js +27 -5
  43. package/dist/exec/plans-condense-findings.js +89 -0
  44. package/dist/exec/plans-core.js +45 -19
  45. package/dist/exec/plans-generation.js +52 -30
  46. package/dist/exec/plans-grade-findings.js +8 -3
  47. package/dist/exec/plans-kata-findings.js +61 -0
  48. package/dist/exec/plans-planning.js +3 -3
  49. package/dist/exec/plans-storage.js +12 -24
  50. package/dist/exec/post-integration.js +162 -0
  51. package/dist/exec/queue-command.js +166 -0
  52. package/dist/exec/queue.js +285 -0
  53. package/dist/exec/register-foreign-wait.js +84 -0
  54. package/dist/exec/register-resume.js +55 -56
  55. package/dist/exec/register.js +26 -22
  56. package/dist/exec/repo-integration-sync.js +21 -5
  57. package/dist/exec/repo-integration.js +21 -1
  58. package/dist/exec/reporter.js +121 -23
  59. package/dist/exec/results.js +106 -25
  60. package/dist/exec/review-completion.js +47 -0
  61. package/dist/exec/review-kata.js +112 -0
  62. package/dist/exec/run/agent-pipeline.js +78 -8
  63. package/dist/exec/run/agent.js +32 -13
  64. package/dist/exec/run/change-scope.js +365 -0
  65. package/dist/exec/run/deferred-cleanup.js +31 -0
  66. package/dist/exec/run/in-place.js +73 -33
  67. package/dist/exec/run/job-lock.js +66 -0
  68. package/dist/exec/run/job-sequence.js +137 -0
  69. package/dist/exec/run/job.js +135 -41
  70. package/dist/exec/run/lifecycle-commands.js +189 -37
  71. package/dist/exec/run/lock.js +22 -1
  72. package/dist/exec/run/mode-shared.js +11 -3
  73. package/dist/exec/run/register-command.js +14 -15
  74. package/dist/exec/run/register-core.js +20 -13
  75. package/dist/exec/run/register-mode.js +77 -17
  76. package/dist/exec/run/register-post-review.js +21 -9
  77. package/dist/exec/run/register-resume.js +95 -31
  78. package/dist/exec/run/register-state.js +23 -15
  79. package/dist/exec/run/register-worktree.js +184 -139
  80. package/dist/exec/run/schedule-mode.js +79 -18
  81. package/dist/exec/run/schedule-prepare.js +204 -59
  82. package/dist/exec/run/schedule-task.js +203 -49
  83. package/dist/exec/run/shared.js +9 -3
  84. package/dist/exec/run/trailing-records.js +35 -0
  85. package/dist/exec/run-records.js +2 -0
  86. package/dist/exec/schedule/schedule.js +116 -4
  87. package/dist/exec/shared.js +1 -1
  88. package/dist/exec/smoke.js +190 -0
  89. package/dist/exec/strategy.js +14 -3
  90. package/dist/exec/task-view.js +6 -4
  91. package/dist/exec/trailing-records.js +242 -0
  92. package/dist/exec/trial-commands.js +8 -4
  93. package/dist/exec/trial-core.js +6 -1
  94. package/dist/exec/validate-records-commit.js +110 -0
  95. package/dist/exec/validate-records.js +148 -0
  96. package/dist/exec/validation-metrics.js +181 -0
  97. package/dist/exec/worktree-cleanup-lock.js +26 -0
  98. package/dist/exec/worktree-command.js +38 -17
  99. package/dist/exec/worktree-ops-commit.js +119 -48
  100. package/dist/exec/worktree-ops-lifecycle.js +77 -48
  101. package/dist/exec/worktree-ops-merge.js +13 -2
  102. package/dist/exec/worktree-ops.js +2 -2
  103. package/dist/exec/worktree.js +32 -4
  104. package/dist/grade/apply.js +32 -6
  105. package/dist/grade/command-apply.js +3 -3
  106. package/dist/grade/command-inspect.js +7 -5
  107. package/dist/grade/command-plan.js +1 -1
  108. package/dist/grade/command-run.js +7 -1
  109. package/dist/grade/command-shared.js +1 -1
  110. package/dist/grade/core.js +18 -5
  111. package/dist/grade/markdown.js +3 -3
  112. package/dist/grade/pipeline-state.js +15 -11
  113. package/dist/grade/plan.js +37 -17
  114. package/dist/grade/result.js +3 -3
  115. package/dist/grade/run.js +87 -11
  116. package/dist/grade/target-discovery.js +17 -4
  117. package/dist/grade/targets.js +12 -11
  118. package/dist/job/definition.js +84 -8
  119. package/dist/job/job.js +109 -39
  120. package/dist/job/noop.js +104 -0
  121. package/dist/register/authoring-sources.js +22 -16
  122. package/dist/register/core.js +2 -0
  123. package/dist/register/create-commands.js +28 -3
  124. package/dist/register/deliverable-target.js +9 -1
  125. package/dist/register/epic.js +104 -26
  126. package/dist/register/event-merge.js +3 -0
  127. package/dist/register/events.js +4 -0
  128. package/dist/register/external-project.js +3 -0
  129. package/dist/register/item.js +6 -0
  130. package/dist/register/maintenance-commands.js +6 -3
  131. package/dist/register/planning.js +7 -14
  132. package/dist/register/register.js +74 -16
  133. package/dist/register/track-domains.js +34 -0
  134. package/dist/register/track-plan.js +78 -0
  135. package/dist/register/transition-commands.js +8 -0
  136. package/dist/register/work-table.js +64 -0
  137. package/dist/review/grade.js +35 -13
  138. package/dist/routine/definition.js +13 -3
  139. package/dist/routine/failure.js +30 -0
  140. package/dist/routine/routine.js +189 -71
  141. package/dist/routine/status.js +62 -0
  142. package/dist/routine/storage.js +33 -0
  143. package/dist/schedule/schedule.js +39 -39
  144. package/dist/schedule/strategy-generate-document.js +26 -14
  145. package/dist/schedule/strategy-generate-scope.js +17 -45
  146. package/dist/schedule/strategy-generate.js +33 -3
  147. package/dist/schedule/strategy-profiles.js +86 -12
  148. package/dist/shared/agent-types.js +7 -0
  149. package/dist/shared/condense-records.js +25 -0
  150. package/dist/shared/cross-process-lock.js +9 -1
  151. package/dist/shared/deprecation.js +8 -0
  152. package/dist/shared/dist-freshness.js +8 -2
  153. package/dist/shared/document-metadata.js +20 -0
  154. package/dist/shared/finding-cause.js +20 -0
  155. package/dist/shared/frontmatter-namespace.js +48 -0
  156. package/dist/shared/git-environment.js +2 -1
  157. package/dist/shared/git.js +186 -16
  158. package/dist/shared/grade-result.js +17 -1
  159. package/dist/shared/lefthook-scaffold.js +3 -0
  160. package/dist/shared/local-config.js +244 -0
  161. package/dist/shared/local-state.js +20 -0
  162. package/dist/shared/markdownlint-config.js +8 -3
  163. package/dist/shared/plan-conventions.js +129 -0
  164. package/dist/shared/plan-templates.js +57 -41
  165. package/dist/shared/run-records.js +224 -0
  166. package/dist/shared/specdojo-config.js +73 -41
  167. package/dist/shared/specdojo-gitignore.js +1 -0
  168. package/dist/shared/text.js +74 -6
  169. package/dist/shared/timeline-index.js +2 -0
  170. package/dist/shared/where-alias.js +13 -0
  171. package/dist/specdojo.js +4 -0
  172. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +11 -2
  173. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +4 -74
  174. package/docs/ja/specdojo/exec-templates/xep-condense-template.md +50 -0
  175. package/docs/ja/specdojo/exec-templates/xep-draft-template.md +17 -5
  176. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +16 -3
  177. package/docs/ja/specdojo/exec-templates/xep-recipe-guided-template.md +15 -5
  178. package/docs/ja/specdojo/exec-templates/xep-recipe-maintenance-template.md +6 -0
  179. package/docs/ja/specdojo/exec-templates/xep-register-template.md +1 -1
  180. package/docs/ja/specdojo/exec-templates/xep-rulebook-maintenance-template.md +6 -0
  181. package/docs/ja/specdojo/exec-templates/xep-sample-maintenance-template.md +6 -0
  182. package/docs/ja/specdojo/exec-templates/xep-template-maintenance-template.md +6 -0
  183. package/docs/ja/specdojo/exec-templates/xer-condense-template.md +25 -0
  184. package/docs/ja/specdojo/exec-templates/xp-common-conventions-template.md +50 -0
  185. package/docs/ja/specdojo/exec-templates/xrp-common-conventions-template.md +30 -0
  186. package/docs/ja/specdojo/guides/branch-workflow-guide.md +1 -1
  187. package/docs/ja/specdojo/guides/docs-editing-guide.md +12 -0
  188. package/docs/ja/specdojo/guides/docs-structure-guide.md +48 -15
  189. package/docs/ja/specdojo/guides/exec-config-guide.md +69 -19
  190. package/docs/ja/specdojo/guides/exec-operation-guide.md +97 -18
  191. package/docs/ja/specdojo/guides/exec-worktree-guide.md +20 -11
  192. package/docs/ja/specdojo/guides/job-sequence-guide.md +77 -0
  193. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +92 -55
  194. package/docs/ja/specdojo/guides/project-move-guide.md +381 -0
  195. package/docs/ja/specdojo/guides/quick-start-guide.md +73 -17
  196. package/docs/ja/specdojo/guides/register-operation-guide.md +26 -6
  197. package/docs/ja/specdojo/guides/remote-host-development-guide.md +2 -0
  198. package/docs/ja/specdojo/guides/review-guide.md +22 -19
  199. package/docs/ja/specdojo/guides/routine-operation-guide.md +23 -12
  200. package/docs/ja/specdojo/guides/ryu-guide.md +23 -13
  201. package/docs/ja/specdojo/guides/schedule-design-guide.md +27 -21
  202. package/docs/ja/specdojo/guides/schedule-operation-guide.md +27 -3
  203. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +5 -4
  204. package/docs/ja/specdojo/guides/timeline-design-guide.md +27 -144
  205. package/docs/ja/specdojo/guides/use-case-guide.md +92 -155
  206. package/docs/ja/specdojo/guides/waza-guide.md +12 -8
  207. package/docs/ja/specdojo/recipes/bac-recipe.md +111 -0
  208. package/docs/ja/specdojo/recipes/bes-recipe.md +141 -0
  209. package/docs/ja/specdojo/recipes/bps-recipe.md +88 -139
  210. package/docs/ja/specdojo/recipes/br-recipe.md +77 -0
  211. package/docs/ja/specdojo/recipes/cdfd-overview-recipe.md +97 -109
  212. package/docs/ja/specdojo/recipes/cdfd-recipe.md +85 -146
  213. package/docs/ja/specdojo/recipes/cdfd-uc-recipe.md +92 -99
  214. package/docs/ja/specdojo/recipes/cnd-recipe.md +135 -0
  215. package/docs/ja/specdojo/recipes/cpd-recipe.md +140 -0
  216. package/docs/ja/specdojo/recipes/cxd-recipe.md +162 -0
  217. package/docs/ja/specdojo/recipes/ifd-recipe.md +145 -0
  218. package/docs/ja/specdojo/recipes/ifx-cmd-recipe.md +112 -90
  219. package/docs/ja/specdojo/recipes/ifx-index-recipe.md +164 -0
  220. package/docs/ja/specdojo/recipes/pm-communication-plan-recipe.md +60 -49
  221. package/docs/ja/specdojo/recipes/pm-members-recipe.md +50 -51
  222. package/docs/ja/specdojo/recipes/pm-organization-recipe.md +59 -48
  223. package/docs/ja/specdojo/recipes/pm-plan-recipe.md +72 -50
  224. package/docs/ja/specdojo/recipes/pm-quality-management-plan-recipe.md +40 -49
  225. package/docs/ja/specdojo/recipes/pm-raci-recipe.md +42 -48
  226. package/docs/ja/specdojo/recipes/pm-roles-recipe.md +52 -81
  227. package/docs/ja/specdojo/recipes/prj-assumptions-constraints-dependencies-recipe.md +64 -91
  228. package/docs/ja/specdojo/recipes/prj-charter-recipe.md +71 -106
  229. package/docs/ja/specdojo/recipes/prj-comparison-of-alternatives-recipe.md +78 -156
  230. package/docs/ja/specdojo/recipes/prj-issues-and-approach-recipe.md +62 -111
  231. package/docs/ja/specdojo/recipes/prj-scope-recipe.md +67 -123
  232. package/docs/ja/specdojo/recipes/prj-stakeholder-register-recipe.md +60 -96
  233. package/docs/ja/specdojo/recipes/prj-success-criteria-and-acceptance-criteria-recipe.md +61 -105
  234. package/docs/ja/specdojo/recipes/stsd-recipe.md +88 -80
  235. package/docs/ja/specdojo/recipes/sysd-critical-flows-recipe.md +129 -0
  236. package/docs/ja/specdojo/recipes/sysd-cross-cutting-policy-recipe.md +146 -0
  237. package/docs/ja/specdojo/recipes/sysd-index-recipe.md +141 -0
  238. package/docs/ja/specdojo/recipes/tsd-recipe.md +149 -129
  239. package/docs/ja/specdojo/references/command-reference.md +303 -148
  240. package/docs/ja/specdojo/references/deliverables-reference.md +30 -16
  241. package/docs/ja/specdojo/references/directory-layout-reference.md +3 -2
  242. package/docs/ja/specdojo/references/specdojo-config-reference.md +54 -18
  243. package/docs/ja/specdojo/rulebooks/atc-index-rulebook.md +101 -257
  244. package/docs/ja/specdojo/rulebooks/atc-rulebook.md +102 -228
  245. package/docs/ja/specdojo/rulebooks/bac-rulebook.md +63 -290
  246. package/docs/ja/specdojo/rulebooks/bdd-rulebook.md +162 -80
  247. package/docs/ja/specdojo/rulebooks/bds-rulebook.md +118 -155
  248. package/docs/ja/specdojo/rulebooks/bes-index-rulebook.md +128 -60
  249. package/docs/ja/specdojo/rulebooks/bes-rulebook.md +70 -94
  250. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +24 -56
  251. package/docs/ja/specdojo/rulebooks/br-rulebook.md +58 -103
  252. package/docs/ja/specdojo/rulebooks/ccd-mermaid-rulebook.md +103 -223
  253. package/docs/ja/specdojo/rulebooks/cdfd-d2-rulebook.md +18 -93
  254. package/docs/ja/specdojo/rulebooks/cdfd-mermaid-rulebook.md +18 -52
  255. package/docs/ja/specdojo/rulebooks/cdfd-overview-rulebook.md +109 -147
  256. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +80 -108
  257. package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +51 -55
  258. package/docs/ja/specdojo/rulebooks/cdr-rulebook.md +144 -0
  259. package/docs/ja/specdojo/rulebooks/cdsd-rulebook.md +81 -68
  260. package/docs/ja/specdojo/rulebooks/cdt-rulebook.md +139 -0
  261. package/docs/ja/specdojo/rulebooks/cld-rulebook.md +9 -184
  262. package/docs/ja/specdojo/rulebooks/clis-rulebook.md +170 -0
  263. package/docs/ja/specdojo/rulebooks/cnd-mermaid-rulebook.md +33 -86
  264. package/docs/ja/specdojo/rulebooks/cnd-rulebook.md +79 -249
  265. package/docs/ja/specdojo/rulebooks/cop-index-rulebook.md +45 -131
  266. package/docs/ja/specdojo/rulebooks/cop-rulebook.md +69 -275
  267. package/docs/ja/specdojo/rulebooks/cpd-mermaid-rulebook.md +20 -112
  268. package/docs/ja/specdojo/rulebooks/cpd-rulebook.md +79 -249
  269. package/docs/ja/specdojo/rulebooks/cxd-mermaid-rulebook.md +12 -145
  270. package/docs/ja/specdojo/rulebooks/cxd-rulebook.md +115 -256
  271. package/docs/ja/specdojo/rulebooks/dct-index-rulebook.md +79 -109
  272. package/docs/ja/specdojo/rulebooks/dct-rulebook.md +119 -174
  273. package/docs/ja/specdojo/rulebooks/dec-rulebook.md +6 -14
  274. package/docs/ja/specdojo/rulebooks/dmd-index-rulebook.md +22 -66
  275. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +36 -94
  276. package/docs/ja/specdojo/rulebooks/dss-rulebook.md +171 -0
  277. package/docs/ja/specdojo/rulebooks/etc-index-rulebook.md +31 -131
  278. package/docs/ja/specdojo/rulebooks/etc-rulebook.md +50 -104
  279. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +93 -57
  280. package/docs/ja/specdojo/rulebooks/ifd-mermaid-rulebook.md +63 -253
  281. package/docs/ja/specdojo/rulebooks/ifx-api-rulebook.md +14 -20
  282. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +79 -76
  283. package/docs/ja/specdojo/rulebooks/ifx-file-rulebook.md +182 -237
  284. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +111 -40
  285. package/docs/ja/specdojo/rulebooks/ifx-msg-rulebook.md +14 -22
  286. package/docs/ja/specdojo/rulebooks/imp-business-rulebook.md +23 -46
  287. package/docs/ja/specdojo/rulebooks/imp-data-rulebook.md +41 -64
  288. package/docs/ja/specdojo/rulebooks/imp-interface-rulebook.md +16 -40
  289. package/docs/ja/specdojo/rulebooks/imp-operations-rulebook.md +34 -61
  290. package/docs/ja/specdojo/rulebooks/imp-test-rulebook.md +27 -50
  291. package/docs/ja/specdojo/rulebooks/itc-index-rulebook.md +70 -199
  292. package/docs/ja/specdojo/rulebooks/itc-rulebook.md +65 -153
  293. package/docs/ja/specdojo/rulebooks/mip-index-rulebook.md +74 -150
  294. package/docs/ja/specdojo/rulebooks/mm-rulebook.md +12 -23
  295. package/docs/ja/specdojo/rulebooks/mtp-rulebook.md +99 -176
  296. package/docs/ja/specdojo/rulebooks/nfr-availability-rulebook.md +35 -61
  297. package/docs/ja/specdojo/rulebooks/nfr-index-rulebook.md +75 -117
  298. package/docs/ja/specdojo/rulebooks/nfr-integrity-rulebook.md +31 -60
  299. package/docs/ja/specdojo/rulebooks/nfr-maintainability-rulebook.md +26 -81
  300. package/docs/ja/specdojo/rulebooks/nfr-operations-rulebook.md +32 -70
  301. package/docs/ja/specdojo/rulebooks/nfr-performance-rulebook.md +45 -87
  302. package/docs/ja/specdojo/rulebooks/nfr-reliability-rulebook.md +48 -101
  303. package/docs/ja/specdojo/rulebooks/nfr-security-safety-rulebook.md +44 -80
  304. package/docs/ja/specdojo/rulebooks/nfr-usability-rulebook.md +59 -127
  305. package/docs/ja/specdojo/rulebooks/opd-index-rulebook.md +31 -50
  306. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +42 -109
  307. package/docs/ja/specdojo/rulebooks/opr-index-rulebook.md +29 -42
  308. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +29 -87
  309. package/docs/ja/specdojo/rulebooks/otp-index-rulebook.md +62 -84
  310. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +11 -61
  311. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +92 -102
  312. package/docs/ja/specdojo/rulebooks/pm-change-request-log-rulebook.md +25 -34
  313. package/docs/ja/specdojo/rulebooks/pm-communication-plan-rulebook.md +30 -53
  314. package/docs/ja/specdojo/rulebooks/pm-issue-log-rulebook.md +23 -35
  315. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +27 -45
  316. package/docs/ja/specdojo/rulebooks/pm-organization-rulebook.md +45 -59
  317. package/docs/ja/specdojo/rulebooks/pm-plan-rulebook.md +56 -66
  318. package/docs/ja/specdojo/rulebooks/pm-quality-management-plan-rulebook.md +54 -62
  319. package/docs/ja/specdojo/rulebooks/pm-raci-rulebook.md +46 -65
  320. package/docs/ja/specdojo/rulebooks/pm-risk-register-rulebook.md +28 -35
  321. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +65 -97
  322. package/docs/ja/specdojo/rulebooks/pr-rulebook.md +6 -18
  323. package/docs/ja/specdojo/rulebooks/prj-assumptions-constraints-dependencies-rulebook.md +48 -78
  324. package/docs/ja/specdojo/rulebooks/prj-charter-rulebook.md +23 -97
  325. package/docs/ja/specdojo/rulebooks/prj-comparison-of-alternatives-rulebook.md +61 -153
  326. package/docs/ja/specdojo/rulebooks/prj-issues-and-approach-rulebook.md +43 -116
  327. package/docs/ja/specdojo/rulebooks/prj-scope-rulebook.md +16 -51
  328. package/docs/ja/specdojo/rulebooks/prj-stakeholder-register-rulebook.md +47 -92
  329. package/docs/ja/specdojo/rulebooks/prj-success-criteria-and-acceptance-criteria-rulebook.md +25 -84
  330. package/docs/ja/specdojo/rulebooks/sac-rulebook.md +44 -107
  331. package/docs/ja/specdojo/rulebooks/sf-index-rulebook.md +106 -32
  332. package/docs/ja/specdojo/rulebooks/sf-rulebook.md +111 -61
  333. package/docs/ja/specdojo/rulebooks/sld-rulebook.md +129 -59
  334. package/docs/ja/specdojo/rulebooks/stc-index-rulebook.md +90 -189
  335. package/docs/ja/specdojo/rulebooks/stc-rulebook.md +45 -105
  336. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +46 -40
  337. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +104 -68
  338. package/docs/ja/specdojo/rulebooks/sysd-critical-flows-rulebook.md +64 -330
  339. package/docs/ja/specdojo/rulebooks/sysd-cross-cutting-policy-rulebook.md +70 -263
  340. package/docs/ja/specdojo/rulebooks/sysd-index-rulebook.md +58 -200
  341. package/docs/ja/specdojo/rulebooks/sysd-rulebook.md +47 -60
  342. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +4 -9
  343. package/docs/ja/specdojo/rulebooks/trc-requirements-to-specs-rulebook.md +69 -71
  344. package/docs/ja/specdojo/rulebooks/trc-requirements-to-tests-rulebook.md +65 -72
  345. package/docs/ja/specdojo/rulebooks/tsd-index-rulebook.md +35 -46
  346. package/docs/ja/specdojo/rulebooks/tsd-rulebook.md +49 -66
  347. package/docs/ja/specdojo/rulebooks/tsp-index-rulebook.md +64 -139
  348. package/docs/ja/specdojo/rulebooks/uis-rulebook.md +91 -161
  349. package/docs/ja/specdojo/rulebooks/utc-index-rulebook.md +49 -144
  350. package/docs/ja/specdojo/rulebooks/utc-rulebook.md +67 -155
  351. package/docs/ja/specdojo/samples/bac-sample.md +106 -21
  352. package/docs/ja/specdojo/samples/bdd-sample.yaml +143 -35
  353. package/docs/ja/specdojo/samples/bds-sample.md +87 -21
  354. package/docs/ja/specdojo/samples/bes-index-sample.md +42 -20
  355. package/docs/ja/specdojo/samples/bes-sample.md +70 -21
  356. package/docs/ja/specdojo/samples/bps-sample.md +42 -54
  357. package/docs/ja/specdojo/samples/br-sample.md +57 -15
  358. package/docs/ja/specdojo/samples/ccd-sample.md +80 -19
  359. package/docs/ja/specdojo/samples/cdfd-sample.md +172 -99
  360. package/docs/ja/specdojo/samples/cdfd-uc-sample.md +9 -7
  361. package/docs/ja/specdojo/samples/cdr-sample.md +78 -0
  362. package/docs/ja/specdojo/samples/cdsd-sample.md +73 -20
  363. package/docs/ja/specdojo/samples/cdt-sample.md +116 -0
  364. package/docs/ja/specdojo/samples/cld-sample.md +3 -30
  365. package/docs/ja/specdojo/samples/clis-sample.md +125 -0
  366. package/docs/ja/specdojo/samples/cnd-sample.md +127 -21
  367. package/docs/ja/specdojo/samples/cpd-sample.md +136 -22
  368. package/docs/ja/specdojo/samples/cxd-sample.md +108 -22
  369. package/docs/ja/specdojo/samples/dct-index-sample.yaml +63 -17
  370. package/docs/ja/specdojo/samples/dec-sample.md +2 -3
  371. package/docs/ja/specdojo/samples/dss-sample.md +175 -0
  372. package/docs/ja/specdojo/samples/gl-sample.yaml +50 -14
  373. package/docs/ja/specdojo/samples/ifd-sample.md +105 -21
  374. package/docs/ja/specdojo/samples/ifx-api-sample.yaml +0 -2
  375. package/docs/ja/specdojo/samples/ifx-cmd-sample.yaml +91 -60
  376. package/docs/ja/specdojo/samples/ifx-file-sample.md +462 -21
  377. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +87 -19
  378. package/docs/ja/specdojo/samples/ifx-msg-sample.yaml +0 -2
  379. package/docs/ja/specdojo/samples/job-sequence.yaml +67 -0
  380. package/docs/ja/specdojo/samples/mip-index-sample.md +98 -20
  381. package/docs/ja/specdojo/samples/pm-communication-plan-sample.md +26 -19
  382. package/docs/ja/specdojo/samples/pm-members-sample.yaml +37 -13
  383. package/docs/ja/specdojo/samples/pm-organization-sample.md +42 -21
  384. package/docs/ja/specdojo/samples/pm-plan-sample.md +78 -26
  385. package/docs/ja/specdojo/samples/pm-quality-management-plan-sample.md +41 -22
  386. package/docs/ja/specdojo/samples/pm-raci-sample.md +63 -28
  387. package/docs/ja/specdojo/samples/pm-roles-sample.yaml +13 -12
  388. package/docs/ja/specdojo/samples/prj-assumptions-constraints-dependencies-sample.md +33 -25
  389. package/docs/ja/specdojo/samples/prj-charter-sample.md +42 -59
  390. package/docs/ja/specdojo/samples/prj-comparison-of-alternatives-sample.md +83 -62
  391. package/docs/ja/specdojo/samples/prj-success-criteria-and-acceptance-criteria-sample.md +30 -33
  392. package/docs/ja/specdojo/samples/sf-index-sample.md +47 -20
  393. package/docs/ja/specdojo/samples/sf-sample.md +109 -21
  394. package/docs/ja/specdojo/samples/sld-sample.md +88 -21
  395. package/docs/ja/specdojo/samples/stsd-sample.md +54 -26
  396. package/docs/ja/specdojo/samples/sysd-critical-flows-sample.md +166 -21
  397. package/docs/ja/specdojo/samples/sysd-cross-cutting-policy-sample.md +178 -21
  398. package/docs/ja/specdojo/samples/sysd-index-sample.md +82 -21
  399. package/docs/ja/specdojo/samples/tml-sample.yaml +4 -1
  400. package/docs/ja/specdojo/samples/uis-sample.md +141 -20
  401. package/docs/ja/specdojo/standards/document-metadata-standard.md +33 -4
  402. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +3 -1
  403. package/docs/ja/specdojo/standards/job-definition-standard.md +24 -9
  404. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +1 -0
  405. package/docs/ja/specdojo/templates/bac-template.md +76 -0
  406. package/docs/ja/specdojo/templates/bes-template.md +56 -0
  407. package/docs/ja/specdojo/templates/br-template.md +64 -0
  408. package/docs/ja/specdojo/templates/cdfd-template.md +81 -54
  409. package/docs/ja/specdojo/templates/cdfd-uc-template.md +9 -5
  410. package/docs/ja/specdojo/templates/cdr-template.md +58 -0
  411. package/docs/ja/specdojo/templates/cnd-template.md +137 -0
  412. package/docs/ja/specdojo/templates/cpd-template.md +129 -0
  413. package/docs/ja/specdojo/templates/cxd-template.md +105 -0
  414. package/docs/ja/specdojo/templates/dct-data-model-cdt-template.yaml +40 -0
  415. package/docs/ja/specdojo/templates/dct-data-model-cld-template.yaml +7 -14
  416. package/docs/ja/specdojo/templates/dct-index-template.md +9 -20
  417. package/docs/ja/specdojo/templates/dct-project-management-template.yaml +5 -1
  418. package/docs/ja/specdojo/templates/ifd-template.md +86 -0
  419. package/docs/ja/specdojo/templates/ifx-cmd-template.yaml +44 -28
  420. package/docs/ja/specdojo/templates/ifx-index-template.yaml +40 -0
  421. package/docs/ja/specdojo/templates/opr-template.md +2 -4
  422. package/docs/ja/specdojo/templates/pm-organization-template.md +9 -3
  423. package/docs/ja/specdojo/templates/pm-plan-template.md +4 -4
  424. package/docs/ja/specdojo/templates/pm-quality-management-plan-template.md +17 -9
  425. package/docs/ja/specdojo/templates/pm-raci-template.md +24 -13
  426. package/docs/ja/specdojo/templates/pm-roles-template.yaml +3 -2
  427. package/docs/ja/specdojo/templates/prj-assumptions-constraints-dependencies-template.md +6 -3
  428. package/docs/ja/specdojo/templates/prj-comparison-of-alternatives-template.md +22 -19
  429. package/docs/ja/specdojo/templates/stsd-template.md +46 -21
  430. package/docs/ja/specdojo/templates/sysd-critical-flows-template.md +94 -0
  431. package/docs/ja/specdojo/templates/sysd-cross-cutting-policy-template.md +122 -0
  432. package/docs/ja/specdojo/templates/sysd-index-template.md +89 -0
  433. package/docs/specdojo/lib/yaml-metadata.cjs +7 -0
  434. package/docs/specdojo/schemas/v1/bdd.schema.yaml +25 -57
  435. package/docs/specdojo/schemas/v1/condense-records.schema.yaml +26 -0
  436. package/docs/specdojo/schemas/v1/dct.schema.yaml +10 -0
  437. package/docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml +3 -0
  438. package/docs/specdojo/schemas/v1/esil.schema.yaml +7 -141
  439. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +5 -1
  440. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +95 -8
  441. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +38 -0
  442. package/docs/specdojo/schemas/v1/exec-plan-frontmatter.schema.yaml +14 -0
  443. package/docs/specdojo/schemas/v1/exec-result-frontmatter.schema.yaml +18 -0
  444. package/docs/specdojo/schemas/v1/finding-cause.schema.yaml +22 -0
  445. package/docs/specdojo/schemas/v1/grade-pipeline-state.schema.yaml +1 -1
  446. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +2 -0
  447. package/docs/specdojo/schemas/v1/ifx-cmd.schema.yaml +65 -5
  448. package/docs/specdojo/schemas/v1/ifx-index.schema.yaml +142 -0
  449. package/docs/specdojo/schemas/v1/job-run.schema.yaml +23 -0
  450. package/docs/specdojo/schemas/v1/job.schema.yaml +63 -2
  451. package/docs/specdojo/schemas/v1/register-events.schema.yaml +2 -0
  452. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +17 -1
  453. package/docs/specdojo/schemas/v1/sch-strategy.schema.yaml +2 -2
  454. package/package.json +10 -7
  455. package/templates/antigravity/orchestrator.md +7 -3
  456. package/templates/claude/agents/specdojo-orchestrator.md +7 -3
  457. package/templates/codex/agents/specdojo-orchestrator.toml +7 -3
  458. package/templates/codex/orchestrator.md +7 -3
  459. package/templates/devcontainer/tmux.conf +6 -0
  460. package/templates/init-exec-defaults.yaml +13 -0
  461. package/templates/lefthook/tools/specdojo-pre-commit.mjs +8 -0
  462. package/templates/opencode/agents/specdojo-orchestrator.md +8 -4
@@ -2,7 +2,7 @@
2
2
  specdojo:
3
3
  id: specdojo:ifx-cmd-recipe
4
4
  type: recipe
5
- status: draft
5
+ status: ready
6
6
  rulebook: specdojo:ifx-cmd-rulebook
7
7
  sample: specdojo:ifx-cmd-sample
8
8
  ---
@@ -11,138 +11,160 @@ specdojo:
11
11
 
12
12
  External Command Interface Specification Writing Recipe
13
13
 
14
- 外部 CLI とのプロセス境界を、呼び出し元と運用担当が同じ判定条件で実装・検証できる契約に仕上げるための作り方を示します。
14
+ 外部 CLI とのプロセス境界を、呼び出し元が成功・失敗を判定し、次の動作を一つに決められる契約に仕上げるための作り方を示す。
15
15
 
16
16
  ## 1. このレシピの使い方
17
17
 
18
- - 最初に、連携で実現する目的と、外部 CLI の安定した公開契約を分けて確認する。CLI の便利機能を先に列挙しない。
19
- - 次に、実行可能ファイル、引数、入出力、終了コードを、成功と主要失敗を再現できる粒度で整理する。
20
- - その後、認証注入、タイムアウト、冪等性、再試行を確認し、秘密値を含めずに運用可能な契約にする。
21
- - 最後に、ESIL の連携目的(Why)、コマンド契約(What)、実行・失敗時の扱い(How)、`spec_ref` と終了カテゴリ(Trace)が一貫しているか確認する。
18
+ - この仕様は、ESIL(外部システム I/F 一覧)の連携目的を引き継ぎ(Why)、呼び出し元が成功後に得る状態と入出力・終了状態の約束を定め(What)、識別信号・再試行・認証の渡し方を決める(How)。起動方法は正本の文書・設定キーへの参照で、仕様自体は ESIL の `spec_ref` からたどれるようにする(Trace)。
19
+ - 「作成前に集める情報」をメモでそろえてから、「全体の作成手順」の順に書く。判断が止まった項目だけ「深掘り手順」で調べ直す。
22
20
 
23
21
  ## 2. 作成前に集める情報
24
22
 
25
- | 項目 | 集める情報 |
26
- | ------------ | ------------------------------------------------------------------------ |
27
- | 連携の目的 | 誰がどのシステムに何を依頼し、成功後にどの状態にするか |
28
- | ESIL 項目 | 連携名、source、target、direction、timing、`spec_ref` |
29
- | CLI 公開契約 | 実行ファイル名、サブコマンド、対応バージョン、引数、構造化出力 |
30
- | ストリーム | stdin の必須性、stdout のデータ形式、stderr の用途、文字コード |
31
- | 終了状態 | 成功、入力不正、認証・認可失敗、制限、一時失敗、恒久失敗の識別方法 |
32
- | 認証・権限 | 認証方式、プロセスへの注入方式、必要権限、シークレット管理境界 |
33
- | 実行制約 | タイムアウト、並列数、ネットワーク要否、実行ディレクトリ、副作用と冪等性 |
34
- | 運用時の判定 | 再試行できる条件、打ち切り条件、再認証が必要な条件、ログから除外する値 |
23
+ | 項目 | 集める情報 | 取り出し元 |
24
+ | -------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
25
+ | 連携目的 | 呼び出し元と連携先、成功後に残る状態、別の契約に分ける操作 | ESIL の対象行、呼び出し元の担当者への確認 |
26
+ | 起動方法の正本 | 起動方法を決める文書・設定キー、対応バージョン、シェルを使う理由 | AI provider CLI は起動設定と exec 設定ガイド、ほかはコマンドリファレンス・公式資料 |
27
+ | 入出力 | stdin の内容と終端、stdout の採用範囲、stderr の用途、ファイルのパスと作成者 | 正本、実際の出力 1 回分、呼び出し元の実装担当への確認 |
28
+ | 終了状態 | 公開された終了コード、同じコードの失敗を分ける追加信号とその定義元 | 正本、検出信号を定義する設定 |
29
+ | 副作用と再実行 | 残る変更、利用枠の消費、途中失敗後に残る状態、重複を防ぐ手段 | 正本、運用担当への確認 |
30
+ | 認証 | 認証方式、渡し方、参照名、供給元、ログの保存先 | 認証を管理する担当への確認(秘密値そのものは集めない) |
31
+ | 制約 | 作業ディレクトリ、時間・並列数・ネットワークの上限と、固定・設定依存・未決定 | 起動設定、呼び出し元の実装担当への確認 |
35
32
 
36
33
  ## 3. 全体の作成手順
37
34
 
38
- 1. ESIL の 1 連携に対応する実行目的を 1 文で書き、別の入出力契約を持つサブコマンドが混じっていないか確認する。
39
- 2. ID、タイトル、状態、準拠ルール、仕様バージョンを設定し、ESIL の `spec_ref` と対応させる。
40
- 3. 実行可能ファイルとサブコマンドを分離し、利用できる CLI バージョン範囲を固定する。
41
- 4. 引数を option と positional に分け、必須性、値の型、供給元、公開可能な例を記載する。
42
- 5. stdin、stdout、stderr の契約を別々に書き、呼び出し元が解析する stdout の安定フィールドを固定する。
43
- 6. 公開された終了コードを共通カテゴリへ写像し、同じ入力で再試行できるか判定する。
44
- 7. 認証方式と注入機構を定義し、秘密値が引数、入出力例、ログに現れないことを確認する。
45
- 8. タイムアウト、並列度、冪等性、再試行、出力解析失敗、認証失敗の処置を定義する。
46
- 9. 最小の成功ケース、入力不正、認証失敗、タイムアウトを想定し、実行側の分岐が一意になるかレビューする。
35
+ 1. 連携単位を最初に決め、ESIL の目的と成功後の状態を 1 文で対応させる。目的・権限・出力が違う操作を混ぜたままだと、終了状態と副作用が一つに決まらない。
36
+ 2. `command` で起動方法の正本を決める。実行ファイル・引数・provider をどこまで書くかは、正本が何を持つかで決まる。
37
+ 3. `streams` と `files` で、成功を観測する信号と、後続処理が採用する出力を分ける。
38
+ 4. `exit_codes` を書く。前の手順で決めた観測信号が、同じコードの失敗を分ける材料になる。
39
+ 5. `side_effects` と冪等性を書く。途中失敗後に残る状態が分からないと、再試行してよいかを決められない。
40
+ 6. `authentication` を書く。
41
+ 7. `execution` と `error_handling` を最後に書く。終了状態と副作用が決まってから再試行の対象を選ぶと、回復の条件がない再試行を避けられる。
47
42
 
48
- ## 4. 各要素の書き方
43
+ ## 4. 各章の書き方
49
44
 
50
- ### 4.1. 実行目的とコマンド
45
+ ### 4.1. 連携単位とメタ情報
51
46
 
52
47
  問い:
53
48
 
54
- - このコマンドの成功によって、連携先または呼び出し元の何が変わるか。
55
- - 実行可能ファイル名とサブコマンドは、対応バージョンで安定しているか。
56
- - 1 回の起動に異なる目的、権限、出力契約が混在していないか。
49
+ - 呼び出し元の何が終われば、この連携は成功か。
50
+ - 複数の操作や provider をまとめても、同じ成功条件で確かめられるか。
57
51
 
58
- 書き方:
52
+ コツ:
59
53
 
60
- - `purpose` はツールの説明ではなく、呼び出し側から見た成果を記載する。
61
- - 実行可能ファイル、サブコマンド、引数を別要素にし、シェル構文を含む 1 本の文字列にしない。
62
- - バージョン範囲は、出力契約と終了コードを確認した範囲だけにする。
54
+ - 「何が残れば成功か」を呼び出し元の担当者に聞くと、分けるべき操作が見つかる。
55
+ - 上位の背景説明を写したくなったら、ESIL の対象行への参照に置き換える。
63
56
 
64
- ### 4.2. 引数とストリーム
57
+ ### 4.2. コマンドと正本参照
65
58
 
66
59
  問い:
67
60
 
68
- - 各引数は誰が生成し、必須性と型をどのように検証できるか。
69
- - stdin を使う理由と、終端なしで入力が完結する条件は何か。
70
- - stdout のどのフィールドを正本とし、stderr のどの情報を診断に使うか。
61
+ - 起動方法を、どの文書・設定キーから解決するか。
62
+ - provider が増えたとき、この仕様のどこを直す必要があるか。
71
63
 
72
- 書き方:
64
+ コツ:
73
65
 
74
- - 引数の例は公開可能なダミー値にし、認証情報と個人環境の絶対パスは使わない。
75
- - 機械処理する stdout は JSON/JSONL など安定形式を選び、必要なフィールドの意味を書く。
76
- - stdout と stderr は別々に記録し、進捗文言を成功値として解析しない。
66
+ - `executable` の括弧やコメント、`purpose` の括弧に provider 名を並べたくなったら書かない。一覧は起動設定の鍵が持ち、`executable` には先頭要素から解決する旨だけを書く。provider を足すたびに複数箇所を直すなら、写しが残っている。
67
+ - 一覧を削るときに、認証の参照名まで消しやすい。参照名は認証の対象を識別するのに要るので残す。
68
+ - シェルを使うかは、宣言ではなく実際の起動設定を見て確かめる。
77
69
 
78
- ### 4.3. 終了コードとエラー処理
70
+ ### 4.3. ストリーム
79
71
 
80
72
  問い:
81
73
 
82
- - 成功、利用者が修正すべき失敗、運用者が解消すべき失敗、自動再試行できる失敗を区別できるか。
83
- - 同じ終了コードが複数の意味に使われる場合、追加の判定信号はあるか。
84
- - 副作用のある実行を再試行しても、結果が重複しない条件は何か。
74
+ - プロセスの終了と業務の完了を、それぞれ何で判断するか。
75
+ - stdout のうち、後続処理が採用するのはどこか。
85
76
 
86
- 書き方:
77
+ コツ:
87
78
 
88
- - CLI 固有の終了コードを共通カテゴリに写像し、リトライ可否を同じ行に置く。
89
- - 汎用的な exit 1 のみで制限や一時失敗と判定せず、専用コードや構造化エラーがある場合だけ自動分類する。
90
- - タイムアウト、出力解析失敗、認証失敗は別の処置とし、一律の再試行にしない。
79
+ - 構造化した報告が出るからといって、stdout 全体が構造化とは限らない。実際の出力を 1 回分見て、進捗が混ざるか確かめる。
80
+ - 報告の項目一覧は写さず、判断に使う意味だけを残す。
91
81
 
92
- ### 4.4. 認証注入と実行制約
82
+ ### 4.4. ファイル
93
83
 
94
84
  問い:
95
85
 
96
- - 認証状態はどの管理境界から、どの機構でプロセスへ渡されるか。
97
- - 呼び出しに必要な最小権限と、認証失敗時の再開条件は何か。
98
- - ネットワーク、実行ディレクトリ、タイムアウト、並列数の制約は何か。
86
+ - 各ファイルのパスは、何を基準に何から決まるか。
87
+ - 各ファイルを作るのは CLI か、呼び出し元か。
99
88
 
100
- 書き方:
89
+ コツ:
101
90
 
102
- - 環境変数名、CLI プロファイル名、workload identity の識別名など、注入の参照だけを書く。
103
- - 秘密値の実値、シークレットファイルの実パス、トークン付き URL は残さない。
104
- - ログのマスク方針とプロセス強制終了後の不完全出力の扱いまで決める。
91
+ - 呼び出し元が保存するログや報告を、CLI の出力に数えやすい。作成者を実装担当に聞いて分ける。
92
+
93
+ ### 4.5. 終了状態と識別条件
94
+
95
+ 問い:
96
+
97
+ - 同じ終了コードを返す失敗を、どの追加信号で分けるか。
98
+ - どの信号にも一致しないとき、呼び出し元はどう動くか。
99
+
100
+ コツ:
101
+
102
+ - 認証失敗などを個別に検出できない実装は多い。検出できない原因は断定せず、人が確かめる扱いにする。
103
+ - 検出パターンを写したくなったら、定義している設定への参照に置き換える。
104
+
105
+ ### 4.6. 副作用と冪等性
106
+
107
+ 問い:
108
+
109
+ - 途中で失敗したとき、外部状態・ファイル・利用枠に何が残るか。
110
+ - 再実行の前に、誰が何を確かめるか。
111
+
112
+ コツ:
113
+
114
+ - 「同じファイルに書くから再実行しても安全」と考えやすい。利用枠の追加消費と、非決定的な編集の差分を聞いて確かめる。
115
+
116
+ ### 4.7. 認証注入
117
+
118
+ 問い:
119
+
120
+ - 認証値は誰が用意し、どの経路でプロセスに渡るか。
121
+ - 引数・stdout・stderr・保存ログのどこで、誰がマスクするか。
122
+
123
+ コツ:
124
+
125
+ - 担当者には秘密値ではなく、仕組みと参照名だけを聞く。例にも実値や個人環境のパスを使わない。
126
+
127
+ ### 4.8. 実行制約と失敗処置
128
+
129
+ 問い:
130
+
131
+ - 時間・並列数の上限は固定か、設定依存か、未決定か。
132
+ - タイムアウトや出力の解析失敗の後、子プロセス・部分出力・既存の変更をどう扱うか。
133
+
134
+ コツ:
135
+
136
+ - 上限が決まっていないとき、検査を通すために値を作りやすい。現在の動作と決めるべき判断を分け、_UNDECIDED_ で残す。
137
+ - 利用制限は、短時間の制限か利用枠の枯渇かを聞き分ける。待ち方が変わる。
105
138
 
106
139
  ## 5. 深掘り手順
107
140
 
108
- 1. ESIL の対象行から、連携の目的、方向、タイミング、失敗時の影響を抽出する。
109
- 2. CLI のヘルプまたは公式の機械可読仕様から、引数、出力形式、終了コードを抜き出す。
110
- 3. 成功、入力不正、認証失敗、レート制限、接続失敗、不正出力の各ケースで観測可能な信号を並べる。
111
- 4. 自動再試行候補ごとに、冪等性、重複防止キー、試行上限、打ち切り後の操作を確認する。
112
- 5. 引数、stdin、stdout、stderr、エラー文言に秘密値が出る可能性を列挙し、それぞれのマスク条件を決める。
113
- 6. 呼び出し側が「成功」「再試行」「人の対応待ち」「入力修正」を仕様だけで分岐できるか確認する。
141
+ 内容が浅いときは、次の順で対応のない主張を探す。
142
+
143
+ 1. 各制約・処置が防ぐ失敗を挙げ、ESIL の目的に結び付かないものを外す。
144
+ 2. 各終了コードについて、入力・追加信号・次の動作を並べ、同じ観測結果に複数の動作が残る箇所を探す。
145
+ 3. 再試行の対象ごとに、副作用から回復する条件があるかを確かめる。
146
+ 4. 正本と同じ一覧・テンプレート・検出パターンを書いた箇所を、参照に戻す。
114
147
 
115
148
  ## 6. 良い例 / 悪い例
116
149
 
117
- | 観点 | 良い例 | 悪い例 |
118
- | ------------ | ----------------------------------------------------------- | -------------------------------------------------- |
119
- | コマンド分離 | `executable: supplier-cli`、`subcommands: [orders, submit]` | `command: "supplier-cli orders submit $FILE"` |
120
- | 引数の供給元 | `value_source: generated` とし、生成元の意味を説明する | 値が固定、設定、利用者入力のどれか不明 |
121
- | stdout | `format: json` と安定フィールドを定義する | 人向けの「成功しました」を文字列一致で判定する |
122
- | stderr | 診断用とし、成否は終了コードと構造化出力で判定する | stderr が空なら成功とみなす |
123
- | 終了カテゴリ | 専用コードと意味を `transient_failure` へ写像する | すべての exit 1 を `rate_limit` と扱う |
124
- | 認証注入 | 環境変数名とシークレットストアの境界だけを記載する | トークン実値または認証ファイルの個人パスを記載する |
125
- | 再試行 | 冪等性キーがある一時失敗だけを上限付きで再試行する | 副作用の有無を確認せず非 0 をすべて再試行する |
126
- | タイムアウト | 子プロセスを終了し、不完全出力を破棄して失敗とする | 親プロセスだけが待機を止め、子プロセスを残す |
150
+ | 観点 | 良い例 | 悪い例 |
151
+ | ------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
152
+ | 連携単位 | 発注登録の成功を受付番号の受領とし、在庫照会とは別の仕様 ID にする | 登録と照会をまとめ、何が終われば成功か分からない |
153
+ | provider 一覧 | `executable` は起動設定の先頭要素から解決すると書き、`purpose` は成功後の状態だけを書く | `executable` の括弧、`purpose` の括弧、コメントに同じ provider 名を並べる |
154
+ | ストリーム | stdout は進捗を含むテキストとし、末尾の報告を取り出して完了を確かめる | 報告があるだけで stdout 全体を JSON とし、exit 0 だけで完了とする |
155
+ | 終了状態 | 非ゼロ終了と設定済みの検出信号が一致したときだけ利用制限とし、ほかは汎用失敗で止める | exit 1 をすべて一時失敗にし、識別できない認証失敗まで自動で再試行する |
156
+ | 失敗処置 | 出力の解析に失敗したら再試行を止め、変更を保持し、確認する人を示す | 「失敗時はリトライする」とだけ書く |
127
157
 
128
158
  ## 7. レビュー観点
129
159
 
130
- | 観点 | 確認内容 |
131
- | ---------------- | ---------------------------------------------------------------------------------- |
132
- | 目的と境界 | ESIL の 1 連携と対応し、API/ファイル/メッセージ仕様の責務を重複定義していないか |
133
- | 実行可能性 | 実行ファイル、サブコマンド、引数、対応バージョンが一意で、シェルに依存しないか |
134
- | 入出力契約 | stdin/stdout/stderr の形式と用途が分離され、機械処理する出力が安定しているか |
135
- | 失敗の識別 | 終了コードと追加信号から、入力修正、再認証、再試行、恒久失敗を分けられるか |
136
- | 認証と秘密保護 | 注入機構と必要権限が明確で、秘密値、個人パス、トークン付き URL が含まれていないか |
137
- | 回復可能性 | タイムアウト、再試行、打ち切り、不完全出力の扱いが定義され、副作用の重複を防げるか |
138
- | トレーサビリティ | 仕様 ID、ESIL の `spec_ref`、終了カテゴリ、根拠文書を安定した識別子でたどれるか |
160
+ | 観点 | 確認内容 |
161
+ | ---------- | ----------------------------------------------------------------------------- |
162
+ | 目的整合 | 成功後の状態が ESIL の連携目的とつながっているか |
163
+ | 回復 | 途中失敗後の状態から再実行を追い、二重処理と利用枠の消費を避ける条件があるか |
164
+ | 委譲の境界 | API・ファイル・メッセージの詳細や起動テンプレートを、正本と別に書いていないか |
139
165
 
140
166
  ## 8. 仕上げチェック
141
167
 
142
- - 仕様 ID と ESIL の `spec_ref` が対応し、`kind: コマンド` の連携を 1 件だけ扱っている。
143
- - 実行可能ファイル、サブコマンド、引数が分離され、シェル構文や秘密値を含む引数がない。
144
- - stdin、stdout、stderr の使用有無、形式、文字コード、意味が判定可能な記述になっている。
145
- - 成功と主要失敗の終了コードが共通カテゴリへ写像され、自動再試行の可否と一致している。
146
- - 認証方式、注入機構、参照名、シークレット管理境界、ログのマスク方針が揃っている。
147
- - タイムアウト、並列数、ネットワーク要否、冪等性、再試行条件、出力解析失敗時の処置を呼び出し側が実装できる。
148
- - 認証情報、個人環境のパス、内部クラス名、プロセス起動ライブラリの実装詳細が残っていない。
168
+ - 根拠のない固定値や、実際の起動方式・作成者と違う宣言が残っていない。
169
+ - 本文・コメント・例に、秘密値、秘密値入り URL、個人環境の認証パスがない。
170
+ - 未決定の項目は、現在の動作と次の確認先をたどれる形で残っている。
@@ -0,0 +1,164 @@
1
+ ---
2
+ specdojo:
3
+ id: specdojo:ifx-index-recipe
4
+ type: recipe
5
+ status: ready
6
+ rulebook: specdojo:ifx-index-rulebook
7
+ sample: specdojo:ifx-index-sample
8
+ ---
9
+
10
+ # 外部システムI/F一覧 作成レシピ
11
+
12
+ External System Interface List Writing Recipe
13
+
14
+ 外部連携の抜けと過剰な詳細化を避け、設計・実装・結合テストの担当が同じ連携対象を特定できる一覧へまとめるための作り方を示す。
15
+
16
+ ## 1. このレシピの使い方
17
+
18
+ - 一覧は、上位の要求から連携が必要な理由(Why)を引き継ぎ、連携ごとの目的・両端・発生条件・異常時の判断(What)を定め、方向と方式(How)を境界の上で示す。連携名と `spec_ref` から詳細契約・結合テスト対象へたどれるようにする(Trace)。
19
+ - 「作成前に集める情報」をメモでそろえてから、「全体の作成手順」の順に書く。
20
+ - 書き終えたら「レビュー観点」で読み直し、「仕上げチェック」で確かめる。
21
+
22
+ ## 2. 作成前に集める情報
23
+
24
+ | 項目 | 集める情報 | 取り出し元・聞く相手 |
25
+ | ------------ | -------------------------------------------------------- | ------------------------------ |
26
+ | 目的と範囲 | 対象の利用場面、連携しないと未完了になる結果、対象外 | 上位の要求・プロジェクトの範囲 |
27
+ | 境界と両端 | 自システム、外部サービス、起動する CLI、受け渡すファイル | 構成図、実装担当への確認 |
28
+ | 発生条件 | 人の操作、業務イベント、周期、起動の前提 | 業務の流れ、利用者への確認 |
29
+ | 詳細契約 | 対象操作に対応する詳細仕様の有無 | 外部 I/F 仕様の文書群 |
30
+ | 失敗の影響 | 未完了・結果不明になる結果、副作用を照合する担当 | 業務担当・運用担当への確認 |
31
+ | 確認者と論点 | 連携ごとの確認者と合意対象、外部側の窓口、未決の方式 | 確認の過程のメモ |
32
+
33
+ 秘密値や個人環境の認証ファイルは集めない。認証は管理主体と方式の確認先だけを控える。
34
+
35
+ ## 3. 全体の作成手順
36
+
37
+ 1. 冒頭コメントに対象範囲と対象外を書く。範囲が決まらないと、連携候補を入れるか外すか決められない。
38
+ 2. 利用場面を一つ選び、境界を越える要求・データ・結果を追って連携単位を切り出す。サービス名や採用ツールの列挙から始めると、目的のない行が混ざる。
39
+ 3. 連携ごとに `source` と `target` を先に決め、その後で `direction`・`kind`・`format` を選ぶ。両端が決まらないと方向が読めない。
40
+ 4. `timing` に発生条件を書く。
41
+ 5. `error_handling` に異常時の判断を書く。
42
+ 6. 詳細契約を対象操作と照らして `spec_ref` を決め、未整備や未決の論点をコメントに残す。
43
+ 7. 連携ごとの確認者と合意対象をコメントに書く。
44
+ 8. 最後に `id`・`title` を決める。対象範囲と連携がそろってからのほうが、一覧を識別できる名前になる。
45
+
46
+ ## 4. 各章の書き方
47
+
48
+ ### 4.1. メタ情報と対象範囲
49
+
50
+ 問い:
51
+
52
+ - 何のシステム・利用場面の一覧か。
53
+ - 将来案と今の対象をどう区別するか。
54
+
55
+ コツ:
56
+
57
+ - 「全外部システム」のような範囲は、利用場面の具体名に置き換える。
58
+ - 上位の背景や目的を写したくなったら、上位成果物への参照に置き換える。
59
+
60
+ ### 4.2. 連携単位と両端
61
+
62
+ 問い:
63
+
64
+ - 相手が同じでも、照会と更新で完了条件や失敗の影響は変わらないか。
65
+ - その連携で何を受け渡し、成功後にどんな結果を得るか。
66
+
67
+ コツ:
68
+
69
+ - 製品名ではなく、得る結果で分ける。名前も結果が伝わるものにする。
70
+ - 一つの行で回復の担当や完了条件が二つ出てきたら、分ける合図にする。
71
+
72
+ ### 4.3. 方向・方式・形式
73
+
74
+ 問い:
75
+
76
+ - 自システムは API を直接呼ぶか、CLI を起動するか、ファイルを置くか。
77
+ - 形式は受け渡すストリーム全体を表しているか。
78
+
79
+ コツ:
80
+
81
+ - 実装担当に「自分たちのコードが何を起動するか」を聞くと、背後のサービスの方式と呼び出し側の方式を取り違えない。
82
+ - 結果の一部が JSON だからといって全体を JSON にしない。入力と結果の形式が違えば内訳をコメントで分ける。
83
+
84
+ ### 4.4. 発生条件
85
+
86
+ 問い:
87
+
88
+ - 誰の操作、どの業務イベントの後に連携するか。
89
+ - 起動してはいけない前提不足は何か。
90
+
91
+ コツ:
92
+
93
+ - 「随時」「適宜」と書きそうになったら、直前に何が終わっているかを聞く。
94
+ - 周期が分からないときは、固定時刻を推測で埋めない。
95
+
96
+ ### 4.5. 異常時の判断
97
+
98
+ 問い:
99
+
100
+ - 応答がないとき、未処理なのか結果不明なのか。
101
+ - 副作用を誰が照合し、その間どの操作を止め、どの結果を保つか。
102
+
103
+ コツ:
104
+
105
+ - 業務担当に「二重に登録・印字されたら何が困るか」を聞くと、再送してよいかが分かる。
106
+ - 引数や再試行の数値を書きたくなったら、回復条件の正本への参照に置き換える。
107
+
108
+ ### 4.6. 詳細参照と未決事項
109
+
110
+ 問い:
111
+
112
+ - 詳細契約はこの操作の成功・結果不明の判断に対応しているか。
113
+ - 決まるまで、どの連携の受入や後続作業を保留するか。
114
+
115
+ コツ:
116
+
117
+ - 文書 ID があるだけで対応を確かめずに `spec_ref` へ入れやすい。対象操作の記述まで開いて照らす。
118
+ - 詳細契約があっても残る論点は、`spec_ref` で解決済みにせずコメントに残す。
119
+
120
+ ### 4.7. 合意と計画への引き継ぎ
121
+
122
+ 問い:
123
+
124
+ - 利用場面・業務影響、契約、期待結果を、それぞれ誰に確かめてもらうか。
125
+ - 外部側の確認が要るなら、窓口は誰か。
126
+
127
+ コツ:
128
+
129
+ - 「関係者確認済み」で済ませず、何について合意したかを聞く。
130
+ - 計画の期日や進捗を写したくなったら、計画や管理記録への参照に置き換える。
131
+
132
+ ## 5. 深掘り手順
133
+
134
+ 内容が浅いときは、次の順で対応のない主張を探す。
135
+
136
+ 1. 各連携について、連携がなくても同じ結果を得られるかを確かめ、目的に対応しない行を外すか範囲の判断へ戻す。
137
+ 2. 各連携の方向と方式が、両端の間の同じ受け渡しを表しているかを確かめる。
138
+ 3. 異常時の判断ごとに、照合の担当と止める操作が決まっているかを確かめる。
139
+ 4. 未決事項ごとに、影響する連携と保留する後続作業を逆にたどる。たどれない論点は、どの連携の論点かを決め直す。
140
+
141
+ ## 6. 良い例 / 悪い例
142
+
143
+ | 観点 | 良い例 | 悪い例 |
144
+ | ---------- | ------------------------------------------------------------ | ---------------------------------------- |
145
+ | 連携単位 | 「商品照会」と「売上登録」を分ける | 「本部連携」一行に全操作を詰める |
146
+ | 発生条件 | 「会計確定と控え保存の後に印字」 | 「適宜印字」 |
147
+ | 異常時 | 「受付結果不明なら記録を保持し担当が照合」 | 「失敗なら即再送」 |
148
+ | 未決の出口 | 照合方式が決まるまで売上登録の受入を保留する、とコメントする | 「契約は後で作る」 |
149
+ | 変更の追跡 | 分割元の連携名と影響する契約・テスト対象を対応づける | 改称後の一覧だけを渡し、旧契約を放置する |
150
+
151
+ ## 7. レビュー観点
152
+
153
+ | 観点 | 確認内容 |
154
+ | ------------ | ------------------------------------------------------------------ |
155
+ | 必要性と範囲 | 各連携が対象の目的に結び付き、将来案と対象外を区別できるか |
156
+ | 境界の一貫性 | 両端、方向、方式、形式が同じ受け渡しを表しているか |
157
+ | 下流への接続 | 連携名から詳細契約と失敗時の確認先へ着き、結合テスト対象を選べるか |
158
+ | 委譲の境界 | 引数・設定値・計画の期日を写さず、参照に置き換えているか |
159
+
160
+ ## 8. 仕上げチェック
161
+
162
+ - 集めた利用場面と一覧を突き合わせ、載っていない連携候補を対象外または判断待ちとして説明できる。
163
+ - 各節の問いへの答えが同じ連携を指し、例の担当や条件を実案件の確認なしで転用していない。
164
+ - 確認待ちの連携を解消済みと扱っていない。
@@ -11,87 +11,98 @@ specdojo:
11
11
 
12
12
  Communication Plan Writing Recipe
13
13
 
14
- ステークホルダーの情報要求を、必要なコミュニケーション機会と証跡へ変換する作り方です。
14
+ 関係者の判断・確認の必要を、機会と記録先へ変える作り方を示す。
15
15
 
16
16
  ## 1. このレシピの使い方
17
17
 
18
- - ステークホルダー登録簿から必要な合意・確認だけを選びます。
19
- - 会議、報告、通知を一つの機会表へ統合します。
20
- - エスカレーションと情報取扱いを加え、重複を削除します。
21
- - 判断・情報要求(Why)、合意・確認する内容と時期(What)、機会・手段・責任(How)を整理し、ステークホルダー ID と証跡で対応を追跡します(Trace)。会議の進行詳細や関係者一覧は本書へ再掲しません。
18
+ - 登録簿の情報要求(Why)を、誰がいつ何を判断・確認するか(What)に変え、手段と責任(How)を決め、記録先とステークホルダー ID でたどれるようにする(Trace)。
22
19
 
23
20
  ## 2. 作成前に集める情報
24
21
 
25
- | 項目 | 集める情報 |
26
- | -------- | ------------------------------------------ |
27
- | 対象 | 判断者、当事者、利用者、協力者、実行ロール |
28
- | 情報要求 | 何を判断・確認・共有する必要があるか |
29
- | 契機 | 作業節目、代表試行、上限超過、公開、変更 |
30
- | 手段 | 登録簿、Pull Request、Issue、試行記録など |
31
- | 証跡 | 判断・確認結果を残す正本 |
32
- | 取扱い | 公開、限定共有、入力禁止の情報 |
22
+ | 項目 | 集める情報 | 取り出し元 |
23
+ | ------------ | ---------------------------------- | ---------------------- |
24
+ | 情報要求 | 誰が何を判断・確認する必要があるか | ステークホルダー登録簿 |
25
+ | 契機 | 判断ゲート、試行の節目、上限超過 | 管理計画 |
26
+ | 判断経路 | 条件ごとに最終判断する人 | PO への確認 |
27
+ | 扱えない情報 | 公開記録や AI Agent へ出せない情報 | 当事者・協働組織 |
33
28
 
34
29
  ## 3. 全体の作成手順
35
30
 
36
- 1. 対象とする主要な合意・確認を決めます。
37
- 2. 各機会について対象、内容、時期、手段、責任、証跡を書きます。
38
- 3. 同じ内容の会議・報告・通知を一行へ統合します。
39
- 4. 人間の判断が必要なエスカレーション条件を定義します。
40
- 5. 情報区分と取扱いを最小限で定義します。
41
- 6. 見直し条件と未決事項を記載します。
31
+ 1. 機会を最初に書く。機会が決まらないと、エスカレーションの条件と扱う情報が決まらない。
32
+ 2. エスカレーション、情報管理と公開、見直し条件と未決事項の順に書く。
33
+ 3. 最後に方針と適用範囲を書く。機会がそろうと、会議を持つかを根拠付きで言える。
42
34
 
43
35
  ## 4. 各章の書き方
44
36
 
45
37
  ### 4.1. 方針と適用範囲
46
38
 
47
- - 常設会議か非同期確認かを決めます。
48
- - 関係者名簿は再掲せず、対象IDまたはRole codeを使います。
49
- - AI Agentは伝達・整理を支援しても、合意主体にしません。
39
+ 問い:
40
+
41
+ - 会議でしか決まらない判断はあるか。
42
+ - 非同期の記録で足りないのはどんな場合か。
43
+
44
+ コツ: 関係者の一覧は登録簿から写さず、参照に置き換える。
50
45
 
51
46
  ### 4.2. コミュニケーション機会
52
47
 
53
- - 一行は一つの判断・確認機会にします。
54
- - 伝える内容より、相手が何を判断・確認するかを明確にします。
55
- - 結果を残す証跡を必ず置きます。
48
+ 問い:
49
+
50
+ - この機会がなければ、誰の判断が止まるか。
51
+ - 相手は何を見て判断するか。
52
+
53
+ コツ: 伝える内容から書くと報告の一覧になる。記録先を答えられない機会は目的が決まっていない。
56
54
 
57
55
  ### 4.3. エスカレーション
58
56
 
59
- - 当事者価値、費用・負荷、品質・安全、公開・権利を分けます。
60
- - 一次対応と最終判断者を区別します。
61
- - 「必要に応じて」だけで終わらせません。
57
+ 問い:
58
+
59
+ - どの条件で判断者が変わるか。
60
+ - 一次対応の人は何を持っていくか。
61
+
62
+ コツ: 緊急度で分けず、誰が決めるかで分ける。AI Agent の出力の疑義は漏れやすい。
62
63
 
63
64
  ### 4.4. 情報管理と公開
64
65
 
65
- - 公開可能情報と入力禁止情報を区別します。
66
- - 個人情報や秘密情報を公開記録とAgent入力へ含めません。
67
- - 生成ビューではなく正本を更新します。
66
+ 問い:
67
+
68
+ - 公開記録と AI Agent に出せない情報は何か。
69
+ - 当事者の発言や試行データは、どの範囲で使う同意があるか。
70
+
71
+ コツ: 生成ビューではなく生成元を直すと書く。
72
+
73
+ ### 4.5. 見直し条件と未決事項
74
+
75
+ 問い:
76
+
77
+ - どの変化で機会の表が合わなくなるか。
78
+ - 未決の論点は、どの機会の相手・時期・手段を変えるか。
79
+
80
+ コツ: 決める人と時期を聞いて書く。
68
81
 
69
82
  ## 5. 深掘り手順
70
83
 
71
- 1. そのコミュニケーションがなければ誰の判断が止まるか確認します。
72
- 2. 同じ対象・内容・時期の行を統合します。
73
- 3. 証跡のない会議や報告を削除します。
74
- 4. 日常課題を登録簿へ移します。
84
+ 1. 機会の各行が、どの情報要求に応えるかを確かめ、対応のない行を外す。
85
+ 2. 記録先のない会議や報告を外す。
86
+ 3. エスカレーションの各条件が、どの機会で見つかるかを確かめる。
75
87
 
76
88
  ## 6. 良い例 / 悪い例
77
89
 
78
- | 観点 | 良い例 | 悪い例 |
79
- | ---- | ---------------------------------------- | ------------------------ |
80
- | 機会 | 代表試行後に利用者が価値と負荷を確認する | 利用者会議を定期開催する |
81
- | 証跡 | 評価結果と採否を試行記録へ残す | 議論したことだけを書く |
82
- | 対象 | ステークホルダーIDまたはRole code | 個人名と連絡先 |
90
+ | 観点 | 良い例 | 悪い例 |
91
+ | ---------------- | ------------------------------------------------- | ---------------------------- |
92
+ | 機会 | 代表試行の後に、利用者が価値と負荷を確かめる | 利用者会議を定期開催する |
93
+ | 証跡 | 評価結果と採否を試行記録へ残す | 議論したことだけを書く |
94
+ | エスカレーション | 費用超過の見込みは、PM が縮小案を作り PO が決める | 重大な問題は速やかに報告する |
83
95
 
84
96
  ## 7. レビュー観点
85
97
 
86
- - ステークホルダーの必要な合意を漏らしていないか。
87
- - 会議・報告・チャネルが重複していないか。
88
- - 判断者と証跡が明確か。
89
- - 公開・非公開の境界が守られているか。
98
+ | 観点 | 確認内容 |
99
+ | ---------- | -------------------------------------------------- |
100
+ | 漏れ | どの機会にも対応しない情報要求がない |
101
+ | 重複 | 同じ相手・内容・時期の確認が複数行に分かれていない |
102
+ | 会議の要否 | 会議ごとに、非同期では決まらない理由を言える |
90
103
 
91
104
  ## 8. 仕上げチェック
92
105
 
93
- - コミュニケーション機会、エスカレーション、情報取扱いがある。
94
- - 目的のない定例会議がない。
95
- - 関係者一覧やRole code定義を再掲していない。
96
- - Agentに合意・承認を委ねていない。
97
- - 各コミュニケーション機会が、元の判断・情報要求と結果の証跡に対応している。
106
+ - 機会の各行が、情報要求と記録先の両方につながる。
107
+ - AI Agent に合意・承認を任せていない。
108
+ - 公開記録の情報が、どの情報区分に当たるかを言える。