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
@@ -14,114 +14,117 @@ specdojo:
14
14
 
15
15
  External Command Interface Specification (ECIS) Documentation Rules
16
16
 
17
- 外部 CLI プロセスを起動する連携について、実行契約、入出力、終了状態、認証注入、失敗時の扱いを YAML 1 ファイルで定義します。ESIL の `kind: コマンド` から参照される、1 つの外部コマンド連携の詳細仕様です。
17
+ 外部 CLI プロセスとの実行契約、入出力、終了判定、副作用、失敗処置、認証注入を YAML 1 ファイルで定義する基準を定めます。
18
18
 
19
19
  ## 1. 全体方針
20
20
 
21
- - 1 ファイルで、1 つの実行目的と共通の入出力契約を持つコマンド連携を定義する。サブコマンドや出力契約が異なる場合はファイルを分ける。
22
- - 呼び出し元と外部 CLI の合意境界に必要な項目を記載し、内部クラス、関数、プロセス起動ライブラリの実装詳細は含めない。
23
- - 実行可能ファイルと引数は配列要素として分離し、既定ではシェルを経由しない。パイプ、リダイレクト、コマンド置換は 1 つのコマンド契約に埋め込まない。
24
- - 認証情報は値ではなく注入方式と参照名だけを定義し、仕様、引数、標準入力、出力例に秘密値を記載しない。
21
+ - **1 連携 1 ファイル**: 実行目的と入出力契約を単位とし、同じ CLI でも目的・権限・出力契約が異なれば分割する。複数 provider をまとめる場合は、共通契約と差異の正本を示す。
22
+ - **正本を分担する**: 共通事項は上位の外部 I/F 一覧・設計、構造・値の制約は schema、起動方法は設定・リファレンスへ委ね、プロセス境界の判断情報に絞る。
23
+ - **起動方式を事実に合わせる**: 原則はシェルを経由しない。例外条件は「コマンドと正本参照」に従う。
24
+ - **共通の運用**: 役割の割り当ては適用先のメンバー定義に、`status`・承認・改訂と廃止・未決事項の登録簿への引き継ぎは [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従う。文書の整形・lint・構造検証はリポジトリの検証で扱い、業務の受入確認に含めない。
25
25
 
26
- ## 2. 位置づけと用語定義
26
+ ## 2. 位置づけ
27
27
 
28
- | 用語 | 定義 |
29
- | -------------- | ------------------------------------------------------------------------------------------------------- |
30
- | 外部コマンド | 対象システムのプロセス境界外にあり、実行可能ファイルと引数を指定して起動する CLI |
31
- | 起動契約 | 実行可能ファイル、サブコマンド、引数、実行ディレクトリ、タイムアウトの合意 |
32
- | ストリーム契約 | stdin、stdout、stderr それぞれの使用有無、形式、文字コード、成功時・失敗時の意味 |
33
- | 認証注入 | シークレットストアや CLI 認証プロファイルから、プロセスに認証状態を渡す方式。秘密値自体は仕様に含めない |
34
- | 終了カテゴリ | CLI 固有の終了コードを、成功、入力不正、認証失敗、一時失敗など呼び出し元が扱える意味へ分類した値 |
35
-
36
- ESIL は連携の存在と方向を一覧化し、本仕様は対応する `spec_ref` の先でプロセス起動の契約を定義します。API、ファイル転送、メッセージングが連携の本体であり CLI が単なる操作ツールの場合は、対応する API/ファイル/メッセージ仕様を正本とし、本仕様との責務の重複を避けます。
28
+ - ESIL(外部システム I/F 一覧)の `spec_ref` の先でプロセス境界の契約を定める。API・ファイル・メッセージ連携の操作手段として CLI を使う場合は、各方式の仕様を正本とする。
29
+ - 起動方法の正本は対象によって選ぶ。SpecDojo 自身のコマンドはコマンドリファレンス、SpecDojo が起動する AI provider CLI は起動設定の `command_template` と [[specdojo:exec-config-guide|exec 設定ガイド]]、その他の外部 CLI は公式リファレンスや製品マニュアルを参照する。
37
30
 
38
31
  ## 3. ファイル命名・ID規則
39
32
 
40
- - ファイル名は `ifx-cmd-<term>.yaml`、`id` は `ifx-cmd-<term>` とし、`<term>` は連携目的または外部 CLI を表す kebab-case にする。
41
- - ESIL の `interfaces[].kind` は `コマンド`、`interfaces[].spec_ref` は本仕様の `id` と一致させる。詳細仕様が未作成の間だけ `TBD` を使用できる。
42
- - 1 つの CLI で複数の実行目的を持つ場合は、`ifx-cmd-git-read` と `ifx-cmd-git-write` のように連携契約単位で分割する。バージョンや状態は ID に含めない。
43
- - package に同梱する sample の ID `specdojo:ifx-cmd-sample` は記述例を識別するための例外であり、ESIL の `spec_ref` には使用しない。
33
+ - ファイル名は `ifx-cmd-<term>.yaml`、ID のローカル部分は `ifx-cmd-<term>` とする。`<term>` は連携目的または外部 CLI を表す kebab-case とし、配置と ID の所有範囲は [[specdojo:docs-structure-guide|ドキュメント構成ガイド]] に従う。
34
+ - ESIL の `interfaces[].kind` は `コマンド` とし、`interfaces[].spec_ref` から本仕様の ID を一意に解決できるようにする。詳細仕様が未作成の間だけ `TBD` を使用できる。
35
+ - 同じ CLI の読取・更新など、契約を分ける場合は `ifx-cmd-git-read` / `ifx-cmd-git-write` のように目的を付ける。バージョンや状態は ID に含めない。
36
+ - 同梱の完成例の ID `specdojo:ifx-cmd-sample` は命名上の例外であり、実際の ESIL の参照先には使用しない。
44
37
 
45
38
  ## 4. 先頭メタ項目
46
39
 
47
- YAML の先頭に次のメタ項目を置きます。
40
+ - 先頭メタ項目と雛形自身のメタ情報は、[[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] の「独立 YAML データファイルのメタ情報」と「生成物メタ情報雛形(`metadata_template`)」に従う。
41
+ - 成果物(雛形では `metadata_template` 内)は `type: api`、`rulebook: specdojo:ifx-cmd-rulebook` とし、`title` で対象と実行目的を識別する。
42
+ - `based_on` は作成根拠、`command.reference` は起動方法の正本参照として区別する。
43
+ - メタ項目の `version` は呼び出し契約の改版、`command.version_constraint` は CLI の対応バージョンを表す。
48
44
 
49
- | キー | 説明 | 必須 |
50
- | -------- | ------------------------------------------------ | ---- |
51
- | id | コマンド連携仕様 ID。成果物では `ifx-cmd-<term>` | ○ |
52
- | type | `api` 固定 | ○ |
53
- | title | 対象と実行目的が分かる仕様名 | ○ |
54
- | status | `draft` / `ready` / `deprecated` | ○ |
55
- | rulebook | `specdojo:ifx-cmd-rulebook` | ○ |
45
+ ## 5. 本文要件
56
46
 
57
- | version | 呼び出し契約の変更を追跡する整数または SemVer | 任意 |
58
- | based_on | 作成時に直接確認した設計・運用文書の ID 配列 | 任意 |
59
- | supersedes | 置き換え対象の文書 ID 配列 | 任意 |
47
+ 構造・型・許容値は `docs/specdojo/schemas/v1/ifx-cmd.schema.yaml` を正本とする。以下は契約の内容要件であり、schema で任意の項目も、本書で必須とした場合は記述する。
60
48
 
61
- `based_on` は実際に内容を確認した文書だけとします。コマンドのバージョン制約はメタ項目の `version` ではなく、`command.version_constraint` に記載します。
49
+ | 対象キー | 必須性 | 契約として定める内容 |
50
+ | ---------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
51
+ | `command` | 必須 | 実行目的、実行ファイルの識別方法、起動方式。`reference` に起動方法を解決できる正本を必ず示す |
52
+ | `streams` | 必須 | stdin の要否、stdout の受領内容と解析対象、stderr の診断用途。各ストリームの形式と意味を明示し、テキストは原則 UTF-8 とする |
53
+ | `files` | ファイル入出力がある場合は必須 | 渡すファイルと作るファイルのパスまたは解決規則、形式、用途、作成・更新主体。内容の構造は対応する schema・仕様を参照する |
54
+ | `side_effects` | 副作用の有無の説明が必須 | 外部状態・ローカル環境への変更と利用枠消費。ルートまたは `execution.side_effects` の一方にまとめ、副作用がなければその旨を書く |
55
+ | `exit_codes` | 必須 | 成功と代表的失敗の終了コード、識別条件、共通カテゴリ、自動再試行の可否 |
56
+ | `authentication` | 必須 | 認証方式、注入機構、参照名、供給元の管理境界、マスク方針。認証不要でもその旨を明示する |
57
+ | `execution` | 必須 | 作業ディレクトリ、時間・並列実行・ネットワークの制約、冪等性の成立条件または保証できない理由 |
58
+ | `error_handling` | 必須 | 再試行の対象と上限・待機方式、タイムアウト、出力解析失敗、認証失敗に対する個別の処置 |
62
59
 
63
- ## 5. YAML構成(標準テンプレ)
60
+ `arguments` は既存仕様との後方互換性のための定義である。新規作成・改訂では引数表を持たず、`command.reference` と入出力の契約へ一本化する。
64
61
 
65
- | ルートキー | 定義内容 | 必須 |
66
- | -------------- | -------------------------------------------------------------------------------- | ---- |
67
- | command | 実行可能ファイル、サブコマンド、用途、バージョン制約、シェル経由の有無 | ○ |
68
- | arguments | option/positional の種別、必須性、型、値の供給元、説明 | ○ |
69
- | streams | stdin、stdout、stderr の使用有無、データ形式、文字コード、契約 | ○ |
70
- | exit_codes | 終了コードと意味、共通カテゴリ、リトライ可否 | ○ |
71
- | authentication | 認証方式、注入機構、参照名、秘密値の供給元、ログのマスク方針 | ○ |
72
- | execution | 実行ディレクトリ、タイムアウト、ネットワーク要否、並列実行数、冪等性 | ○ |
73
- | error_handling | 再試行対象、試行上限、待機方式、タイムアウト時、出力解析失敗時、認証失敗時の処置 | ○ |
62
+ ## 6. 記述ガイド
74
63
 
75
- 引数が無いコマンドは `arguments: []` を明示できます。`exit_codes` は空配列にせず、少なくとも成功と代表的な失敗を記載します。
64
+ ### 6.1. 連携単位とメタ情報
76
65
 
77
- ## 6. 記述ガイド
66
+ - **判断基準**: ESIL の目的と成功後の状態が対応し、1 ファイルを一つの契約として検証できること。provider 一覧や設定値を複数キーへ繰り返さない。
67
+ - **影響の照合先**: ESIL の参照行、呼び出し元の業務完了・回復条件、起動設定・入出力処理、正常・異常・再試行の検証を照合する。
68
+ - **良い例**: 読取と更新を別 ID にし、`title` に対象と目的を書く。provider ごとに実行ファイルが変わるときは、`executable` に設定の該当キーから解決する旨を示し、一覧自体は設定へ委ねる。
69
+ - **悪い例**: 一つの仕様に読取・登録・削除を混在させる。設定の provider 一覧を目的・実行ファイル・コメントへそれぞれ転載する。
70
+
71
+ ### 6.2. コマンドと正本参照
72
+
73
+ - **判断基準**: `purpose` で呼び出し元から見た成功後の状態を示し、`reference` で正本の文書・設定キー・対象操作を特定する。通常は実行ファイルとサブコマンドを分け、`shell: false` とする。
74
+ - **シェル起動の例外**: 呼び出し元が管理された起動設定を展開し、シェルが必要な場合は `shell: true` を認める。理由、テンプレートの正本と管理境界、展開値の検証・制限の参照先を示す。利用者入力の無制限なシェル構文評価は認めない。テンプレート全文や複数コマンドの処理手順は転載しない。
75
+ - **良い例**: AI provider CLI では `reference` に `.specdojo/exec-defaults.yaml` の `providers.<provider>.command_template` と exec 設定ガイドを示す。`shell: true` の理由を stdin から起動引数への変換として説明し、設定の保護と展開値の検証は同ガイドの契約を参照する。
76
+ - **悪い例**: 実際はシェルを使うのに `false` と書く。「外部 CLI だから」という理由だけで `true` にする。`executable` に引数やパイプを連結し、起動設定と別のコマンド全文を管理する。
78
77
 
79
- ### 6.1. command と arguments
78
+ ### 6.3. ストリーム
80
79
 
81
- - `command.executable` は実行可能ファイル名または配布済みパスを記載し、引数やパイプを連結しない。`command.subcommands` は起動順の文字列配列とする。
82
- - `command.shell` は `false` 固定とする。複数コマンドの連携は実行側のワークフローで表し、文字列のシェルスクリプトとして仕様化しない。
80
+ - **判断基準**: stdin は入力内容と終端、stdout は採用範囲、stderr は診断用途を記す。stdin を使わない場合も要否と形式を明示する。出力の詳細構造は正本へ委ね、判定に必要な意味を残す。
81
+ - **良い例**: 進捗が混在する stdout では、末尾の構造化報告の抽出範囲と欠落・解析失敗時の扱いを示す。終了コードと報告内容の両方で完了を判断するなら、各々が保証する範囲を書く。
82
+ - **悪い例**: 構造化部分があることを理由に stdout 全体を JSON と記す。「CLI の既定出力」とだけ書く。stderr が空なら成功と判定する。
83
83
 
84
- - `arguments[].kind` は `option` / `positional`、`value_type` は `string` / `integer` / `boolean` / `path` / `json`、`value_source` は `literal` / `config` / `generated` のいずれかとする。
85
- - positional 引数は `position` を 1 始まりで付け、option 引数は `name` に CLI の表記を記載する。可変値は `example` に実値ではなく公開可能な例を置く。
84
+ ### 6.4. ファイル
86
85
 
87
- ### 6.2. stdin/stdout/stderr
86
+ - **判断基準**: 入出力別に、パスの基準、可変部の供給元と書式、形式、作成・更新・読取主体、内容仕様の正本を特定する。`description` など既存欄で説明し、専用キーやフィールド一覧を追加しない。CLI の生成物と呼び出し元の実行記録を区別する。
87
+ - **入出力がない場合**: 入出力のない側の配列は `[]` または省略で表し、どちらも該当の入出力がないことを意味する。入出力が一切なければ `files` 自体を省略できる。未確認の場合と混同しない。
88
+ - **良い例**: 入力の相対パス、可変部分の解決元(確定済み取引の識別情報)、作成主体(呼び出し元)、内容仕様の正本を示す。CLI が出力ファイルを作らない例では `outputs: []` とし、呼び出し元のログ保存と分ける。
89
+ - **悪い例**: 出力を「各種ファイル」とだけ書く。呼び出し元が保存するログや別段階で作成する result を、同じ CLI の出力として列挙する。入力ファイルの作成主体や可変部分の解決元が書かれていない。
88
90
 
89
- - `streams.stdin.mode` は `none` / `optional` / `required` とし、`required` または `optional` の場合は `format`、`encoding`、入力の意味を記載する。
90
- - `streams.stdout` は成功時に呼び出し元が解析する形式と最小契約を記載する。機械処理する場合は `json` または `jsonl` を優先し、人向けの可変文言に依存しない。
91
- - `streams.stderr` は進捗、警告、失敗詳細のどれが出力されるかを記載する。stderr の文言だけで成否を判定せず、終了コードと構造化出力を優先する。
92
- - 形式は `text` / `json` / `jsonl` / `yaml` / `binary` / `none` から選び、テキスト形式には原則 `UTF-8` を指定する。
91
+ ### 6.5. 終了状態と識別条件
93
92
 
94
- ### 6.3. exit_codes
93
+ - **判断基準**: 各終了コードから呼び出し元の次の動作を判断できること。同じコードが複数の意味を持つ場合は、`meaning` に追加信号・判定順・未分類時の扱いを記す。正本に定義された構造化エラーや stdout / stderr の検出条件を参照できればよく、検出パターンの一覧は転載しない。
94
+ - **カテゴリの使い分け**: `success` はプロセスの成功を表し、業務完了に別の条件があれば区別する。`input_error` は入力修正、`authentication_error` は再認証、`authorization_error` は権限の見直し、`permanent_failure` は原因解消を必要とする。`rate_limit` は利用制限、`transient_failure` は一時的障害であり、再試行できる条件を失敗処置で定める。
95
+ - **良い例**: 非ゼロ終了と設定済み検出信号が一致した場合だけ利用制限とし、ほかの非ゼロ終了は汎用失敗として停止する。認証失敗を個別検出できない実装なら、その制約と手動確認の扱いも書く。
96
+ - **悪い例**: 汎用的な exit 1 をすべて一時失敗とする。識別信号がないのに原因別の自動分岐ができると宣言する。exit 0 だけで成果物の検証まで成功したとみなす。
95
97
 
96
- | キー | 記載内容 | 必須 |
97
- | ------- | ------------------------------------------ | ---- |
98
- | code | CLI が返す整数の終了コード | ○ |
99
- | meaning | CLI 固有の意味と呼び出し元が識別できる条件 | ○ |
98
+ ### 6.6. 副作用と冪等性
100
99
 
101
- | category | `success` / `input_error` / `authentication_error` / `authorization_error` / `rate_limit` / `transient_failure` / `permanent_failure` | ○ |
102
- | retryable | 同じ入力で自動再試行してよいか | ○ |
100
+ - **判断基準**: 永続的な変更、利用枠・課金への影響、変更してはならない範囲を示す。`idempotency` は同一入力での再実行の保証を表し、自動再試行する場合は二重処理を防ぐ条件を明記する。保証がなければ、再開前に既存状態をどう扱うかを書く。
101
+ - **良い例**: 発注登録では同じリクエスト ID による重複排除を条件とする。非決定的な編集処理では冪等性を保証せず、同じ作業ディレクトリの差分を引き継ぎ、確認して再開する条件を示す。
102
+ - **悪い例**: 同じファイル名へ書くという理由だけで業務処理全体が冪等とする。再試行による二重登録や利用枠の追加消費を説明しない。
103
103
 
104
- 複数の意味に使われる終了コードは、追加の判定条件を `meaning` に記載します。汎用的な非 0 のみを `rate_limit` や `transient_failure` とみなさず、専用コードまたは構造化出力で識別できる場合だけその category を使用します。
104
+ ### 6.7. 認証注入
105
105
 
106
- ### 6.4. authentication
106
+ - **判断基準**: `method` と `injection` は認証の種類と渡し方を分け、`names` には必要な参照名を書く。認証値は起動引数や標準入力へ埋め込まない。`secret_source` には管理境界、`log_policy` には引数・環境変数・stdout・stderr・保存ログのマスク対象とタイミングを書く。認証不要の場合の表現も schema の制約を満たすこと。
107
+ - **良い例**: CLI のログインプロファイルを利用する場合、プロファイル名と保管を担う管理境界を示し、呼び出し元が秘密値を注入しないことを書く。環境変数で渡す場合は変数名だけを示す。
108
+ - **悪い例**: 認証トークンの実値、秘密値入り URL、個人環境の認証ファイルの実パスを例示する。プロファイルを利用するのに環境変数注入と記す。
107
109
 
108
- - `method` は `none` / `api_token` / `oauth` / `ssh_key` / `provider_login` から選び、連携先が要求する認証の種類を示す。
109
- - `injection.mechanism` は `none` / `environment_variable` / `credential_store` / `workload_identity` / `cli_profile` から選び、必要な参照名を `injection.names` に列挙する。
110
- - `secret_source` に値を供給する管理境界を記載し、`log_policy` に引数、環境変数、stdout/stderr のマスク条件を記載する。
111
- - 認証トークン、秘密鍵、パスワード、認証プロファイルの実パスを記載しない。コマンド引数への秘密値の埋め込みも許可しない。
110
+ ### 6.8. 実行制約と失敗処置
112
111
 
113
- ### 6.5. execution と error_handling
112
+ - **判断基準**: 作業ディレクトリと時間・並列実行・ネットワークの制約は公開契約や確認した実装・設定を根拠にする。schema で参照値や上限なしを表せず判断が未了なら、許容されるプレースホルダと共通ラベルで現在動作・不足する判断・影響・確認先を残し、架空の固定値で埋めない。
113
+ - **再試行と回復**: `retryable` と `retry.on_categories` を照合し、対象条件、試行上限の数え方、待機方式を揃える。利用制限でも短時間の制限と利用枠の枯渇を区別し、実際の停止・待機・切替条件は正本へ委ねる。タイムアウト時の子プロセスと部分出力、出力解析失敗時の既存変更、認証失敗時の確認先を個別に定める。
114
+ - **良い例**: タイムアウトが未決定なら、現在は終了まで待つことと、上限・終了処置を決める必要を区別して記す。出力異常時は自動再試行を止め、変更を保持して人の確認または再開に委ねる。
115
+ - **悪い例**: schema を通すためだけに時間や並列数を捏造する。「失敗時はリトライ」とだけ書く。認証・認可・入力不正を待機だけで回復する一時失敗として扱う。
114
116
 
115
- - `execution.timeout_seconds` は 1 回の起動上限、`max_parallel` は同時実行上限とし、コマンドの公開契約や実測根拠から決める。
116
- - `execution.idempotency` は `guaranteed` とその条件を記載する。副作用のあるコマンドを再試行する場合は、リクエスト ID など重複実行を防ぐ条件を明示する。
117
- - `error_handling.retry.on_categories` は `exit_codes` の category と一致させ、`max_attempts` と `backoff` を記載する。認証失敗や入力不正は自動再試行しない。
117
+ ### 6.9. 成果物の検証手順
118
118
 
119
- - タイムアウト時のプロセス終了、不完全出力の破棄、stdout の解析失敗、認証失敗の再認証依頼をそれぞれ別のキーで記載する。
119
+ - **判断基準**: 作成・改訂した仕様 YAML の契約を、参照する正本と起動・入出力・報告解析の検証入口へ照合できること。CLI を起動する検証の詳細は参照先へ委ねる。
120
+ - **確認手順**: 正本の実在と適用範囲、ファイルの作成主体・可変パス・内容仕様を照合し、正常、同じコードの異なる失敗、出力欠落、途中失敗後の再実行を追う。入力・観測信号・期待結果と検証入口の参照先、確認結果を実行記録に残す。
121
+ - **合格条件**: 各ケースの業務完了判定、次の動作、副作用と回復条件が契約と一致する。識別不能な失敗は自動分類せず手動確認へつながり、未決事項は現在動作と影響をたどれること。不一致は仕様または参照先を修正し、該当ケースを再確認する。
122
+ - **良い例**: 同じ exit 1 を追加信号と判定順で分類し、途中失敗後の再実行で二重処理を防ぐ条件まで正本・検証結果と照合する。
123
+ - **悪い例**: schema 合格だけで業務完了や再試行の安全性も保証したとみなす。検証入口を示さず「動作確認済み」とする。
120
124
 
121
125
  ## 7. 禁止事項
122
126
 
123
- - 実行可能ファイル、サブコマンド、引数を 1 本のシェル文字列として記載しない。`command.shell: true`、パイプ、リダイレクト、コマンド置換は使用しない。
124
- - トークン、パスワード、秘密鍵、秘密値を含む URL、個人環境に固有の認証パスを本文や例に記載しない。
125
- - 標準出力と標準エラーを混同したり、出力形式を「CLI の既定」とだけ記載したり、終了コードの意味を定義せずに成否判定を文言解析に依存しない。
126
- - 副作用があるコマンドを冪等性条件なしで自動再試行対象にしない。認証失敗、認可失敗、入力不正を一時失敗として扱わない。
127
- - DB 物理構造、内部クラス名、プロセス起動ライブラリの API 呼び出し、スクリプト全文などの実装詳細を含めない。
127
+ - 引数表、起動テンプレート全文、検出パターン一覧を正本と別に管理すること。
128
+ - シェル起動の例外条件を満たさず `shell: true` とすること、または実際の起動方式を隠して `false` とすること。
129
+ - stdout / stderr、プロセス終了 / 業務完了、CLI の生成物 / 呼び出し元の記録を混同すること。
130
+ - 追加信号のない終了コードだけで原因を断定したり、副作用の回復条件がないまま自動再試行したりすること。