specdojo 0.6.0 → 0.8.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 (366) hide show
  1. package/.github/agents/specdojo-orchestrator.md +3 -2
  2. package/CHANGELOG.md +193 -0
  3. package/README.md +2 -2
  4. package/dist/catalog/build.js +24 -1
  5. package/dist/catalog/plan.js +1 -1
  6. package/dist/catalog/scaffold.js +4 -1
  7. package/dist/commands/agent.js +33 -0
  8. package/dist/commands/init.js +6 -1
  9. package/dist/commands/night-orchestrator.js +6 -4
  10. package/dist/commands/orchestrator.js +10 -1
  11. package/dist/dashboard/dashboard-timeline.js +18 -16
  12. package/dist/dashboard/dashboard.js +612 -259
  13. package/dist/dashboard/epic-plan.js +81 -0
  14. package/dist/dashboard/exec-records.js +16 -20
  15. package/dist/dashboard/routines.js +8 -6
  16. package/dist/dashboard/timeline-build.js +5 -9
  17. package/dist/dashboard/timeline.js +9 -4
  18. package/dist/devcontainer/command.js +18 -0
  19. package/dist/devcontainer/host-script.js +21 -0
  20. package/dist/devcontainer/scaffold.js +22 -3
  21. package/dist/docs/frontmatter-namespace.js +1 -48
  22. package/dist/docs/yaml-pages.js +125 -3
  23. package/dist/exec/agent-config.js +22 -0
  24. package/dist/exec/agent-plan.js +3 -2
  25. package/dist/exec/antigravity-session.js +154 -0
  26. package/dist/exec/commands.js +69 -21
  27. package/dist/exec/commit-hook-skips.js +78 -0
  28. package/dist/exec/core.js +19 -7
  29. package/dist/exec/events.js +159 -8
  30. package/dist/exec/evidence.js +64 -16
  31. package/dist/exec/handoff.js +9 -13
  32. package/dist/exec/limit.js +1 -1
  33. package/dist/exec/mechanical-result.js +45 -0
  34. package/dist/exec/migrate-records.js +249 -0
  35. package/dist/exec/parent-validation.js +160 -12
  36. package/dist/exec/pipeline-state.js +27 -5
  37. package/dist/exec/plan-markdownlint.js +89 -0
  38. package/dist/exec/plans-condense-findings.js +89 -0
  39. package/dist/exec/plans-core.js +24 -17
  40. package/dist/exec/plans-generation.js +52 -25
  41. package/dist/exec/plans-grade-findings.js +8 -3
  42. package/dist/exec/plans-kata-findings.js +61 -0
  43. package/dist/exec/plans-planning.js +3 -3
  44. package/dist/exec/plans-storage.js +12 -24
  45. package/dist/exec/register-resume.js +69 -42
  46. package/dist/exec/register.js +26 -22
  47. package/dist/exec/repo-integration-sync.js +8 -4
  48. package/dist/exec/repo-integration.js +21 -1
  49. package/dist/exec/reporter.js +121 -23
  50. package/dist/exec/results.js +85 -24
  51. package/dist/exec/review-completion.js +47 -0
  52. package/dist/exec/review-kata.js +109 -0
  53. package/dist/exec/run/agent-pipeline.js +75 -6
  54. package/dist/exec/run/agent.js +20 -7
  55. package/dist/exec/run/in-place.js +69 -32
  56. package/dist/exec/run/job.js +81 -24
  57. package/dist/exec/run/lifecycle-commands.js +264 -43
  58. package/dist/exec/run/mode-shared.js +11 -3
  59. package/dist/exec/run/register-command.js +12 -10
  60. package/dist/exec/run/register-core.js +20 -13
  61. package/dist/exec/run/register-mode.js +12 -12
  62. package/dist/exec/run/register-post-review.js +21 -9
  63. package/dist/exec/run/register-resume.js +28 -18
  64. package/dist/exec/run/register-state.js +10 -7
  65. package/dist/exec/run/register-worktree.js +60 -30
  66. package/dist/exec/run/schedule-mode.js +26 -6
  67. package/dist/exec/run/schedule-prepare.js +228 -45
  68. package/dist/exec/run/schedule-task.js +132 -25
  69. package/dist/exec/run/shared.js +4 -3
  70. package/dist/exec/run/trailing-records.js +35 -0
  71. package/dist/exec/run-records.js +2 -0
  72. package/dist/exec/strategy.js +1 -0
  73. package/dist/exec/trailing-records.js +242 -0
  74. package/dist/exec/trial-commands.js +3 -2
  75. package/dist/exec/validate-records-commit.js +110 -0
  76. package/dist/exec/validate-records.js +148 -0
  77. package/dist/exec/worktree-command.js +29 -16
  78. package/dist/exec/worktree-ops-commit.js +118 -59
  79. package/dist/exec/worktree-ops-lifecycle.js +77 -44
  80. package/dist/exec/worktree-ops-merge.js +13 -2
  81. package/dist/exec/worktree-ops.js +2 -2
  82. package/dist/exec/worktree.js +19 -2
  83. package/dist/grade/apply.js +32 -6
  84. package/dist/grade/command-inspect.js +2 -2
  85. package/dist/grade/command-run.js +2 -0
  86. package/dist/grade/command-shared.js +1 -1
  87. package/dist/grade/core.js +18 -5
  88. package/dist/grade/markdown.js +3 -3
  89. package/dist/grade/pipeline-state.js +15 -11
  90. package/dist/grade/plan.js +37 -17
  91. package/dist/grade/result.js +3 -3
  92. package/dist/grade/run.js +23 -3
  93. package/dist/grade/target-discovery.js +17 -4
  94. package/dist/grade/targets.js +12 -11
  95. package/dist/job/job.js +31 -17
  96. package/dist/job/noop.js +104 -0
  97. package/dist/register/core.js +2 -0
  98. package/dist/register/create-commands.js +28 -3
  99. package/dist/register/deliverable-target.js +9 -1
  100. package/dist/register/epic.js +104 -26
  101. package/dist/register/event-merge.js +3 -0
  102. package/dist/register/events.js +4 -0
  103. package/dist/register/external-project.js +3 -0
  104. package/dist/register/item.js +6 -0
  105. package/dist/register/maintenance-commands.js +4 -1
  106. package/dist/register/planning.js +7 -14
  107. package/dist/register/register.js +74 -32
  108. package/dist/register/track-domains.js +34 -0
  109. package/dist/register/track-plan.js +78 -0
  110. package/dist/register/transition-commands.js +8 -0
  111. package/dist/register/work-table.js +64 -0
  112. package/dist/review/grade.js +35 -13
  113. package/dist/routine/definition.js +4 -3
  114. package/dist/routine/failure.js +30 -0
  115. package/dist/routine/routine.js +56 -32
  116. package/dist/routine/storage.js +33 -0
  117. package/dist/schedule/schedule.js +1 -0
  118. package/dist/schedule/strategy-generate-document.js +26 -14
  119. package/dist/schedule/strategy-generate-scope.js +17 -45
  120. package/dist/schedule/strategy-generate.js +33 -3
  121. package/dist/schedule/strategy-profiles.js +86 -12
  122. package/dist/shared/agent-types.js +2 -0
  123. package/dist/shared/condense-records.js +25 -0
  124. package/dist/shared/deprecation.js +8 -0
  125. package/dist/shared/document-metadata.js +20 -0
  126. package/dist/shared/finding-cause.js +20 -0
  127. package/dist/shared/frontmatter-namespace.js +48 -0
  128. package/dist/shared/git.js +149 -15
  129. package/dist/shared/grade-result.js +17 -1
  130. package/dist/shared/local-state.js +20 -0
  131. package/dist/shared/markdownlint-config.js +8 -3
  132. package/dist/shared/plan-conventions.js +129 -0
  133. package/dist/shared/plan-templates.js +57 -41
  134. package/dist/shared/provider-scaffold.js +2 -0
  135. package/dist/shared/run-records.js +224 -0
  136. package/dist/shared/specdojo-config.js +39 -21
  137. package/dist/shared/specdojo-gitignore.js +1 -0
  138. package/dist/shared/text.js +65 -5
  139. package/dist/shared/timeline-index.js +2 -0
  140. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +11 -2
  141. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +4 -74
  142. package/docs/ja/specdojo/exec-templates/xep-condense-template.md +50 -0
  143. package/docs/ja/specdojo/exec-templates/xep-draft-template.md +17 -5
  144. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +16 -3
  145. package/docs/ja/specdojo/exec-templates/xep-recipe-guided-template.md +15 -5
  146. package/docs/ja/specdojo/exec-templates/xep-recipe-maintenance-template.md +6 -0
  147. package/docs/ja/specdojo/exec-templates/xep-register-template.md +1 -1
  148. package/docs/ja/specdojo/exec-templates/xep-rulebook-maintenance-template.md +6 -0
  149. package/docs/ja/specdojo/exec-templates/xep-sample-maintenance-template.md +6 -0
  150. package/docs/ja/specdojo/exec-templates/xep-template-maintenance-template.md +6 -0
  151. package/docs/ja/specdojo/exec-templates/xer-condense-template.md +25 -0
  152. package/docs/ja/specdojo/exec-templates/xp-common-conventions-template.md +50 -0
  153. package/docs/ja/specdojo/exec-templates/xrp-common-conventions-template.md +30 -0
  154. package/docs/ja/specdojo/guides/branch-workflow-guide.md +1 -1
  155. package/docs/ja/specdojo/guides/docs-editing-guide.md +48 -0
  156. package/docs/ja/specdojo/guides/docs-structure-guide.md +48 -15
  157. package/docs/ja/specdojo/guides/exec-config-guide.md +61 -28
  158. package/docs/ja/specdojo/guides/exec-operation-guide.md +61 -13
  159. package/docs/ja/specdojo/guides/exec-worktree-guide.md +20 -11
  160. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +4 -2
  161. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +92 -55
  162. package/docs/ja/specdojo/guides/project-move-guide.md +381 -0
  163. package/docs/ja/specdojo/guides/quick-start-guide.md +589 -807
  164. package/docs/ja/specdojo/guides/register-operation-guide.md +26 -4
  165. package/docs/ja/specdojo/guides/remote-host-development-guide.md +33 -4
  166. package/docs/ja/specdojo/guides/review-guide.md +22 -19
  167. package/docs/ja/specdojo/guides/routine-operation-guide.md +14 -8
  168. package/docs/ja/specdojo/guides/ryu-guide.md +23 -13
  169. package/docs/ja/specdojo/guides/schedule-design-guide.md +7 -4
  170. package/docs/ja/specdojo/guides/schedule-operation-guide.md +41 -3
  171. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +5 -4
  172. package/docs/ja/specdojo/guides/timeline-design-guide.md +27 -144
  173. package/docs/ja/specdojo/guides/use-case-guide.md +471 -74
  174. package/docs/ja/specdojo/recipes/bac-recipe.md +94 -0
  175. package/docs/ja/specdojo/recipes/bes-recipe.md +105 -0
  176. package/docs/ja/specdojo/recipes/br-recipe.md +84 -0
  177. package/docs/ja/specdojo/recipes/cdfd-overview-recipe.md +88 -86
  178. package/docs/ja/specdojo/recipes/cdfd-uc-recipe.md +108 -122
  179. package/docs/ja/specdojo/recipes/cnd-recipe.md +125 -0
  180. package/docs/ja/specdojo/recipes/cpd-recipe.md +126 -0
  181. package/docs/ja/specdojo/recipes/cxd-recipe.md +145 -0
  182. package/docs/ja/specdojo/recipes/ifd-recipe.md +134 -0
  183. package/docs/ja/specdojo/recipes/ifx-cmd-recipe.md +135 -86
  184. package/docs/ja/specdojo/recipes/ifx-index-recipe.md +130 -0
  185. package/docs/ja/specdojo/recipes/pm-organization-recipe.md +29 -26
  186. package/docs/ja/specdojo/recipes/pm-plan-recipe.md +35 -26
  187. package/docs/ja/specdojo/recipes/pm-quality-management-plan-recipe.md +38 -28
  188. package/docs/ja/specdojo/recipes/pm-raci-recipe.md +39 -31
  189. package/docs/ja/specdojo/recipes/pm-roles-recipe.md +26 -28
  190. package/docs/ja/specdojo/recipes/prj-assumptions-constraints-dependencies-recipe.md +10 -8
  191. package/docs/ja/specdojo/recipes/prj-comparison-of-alternatives-recipe.md +18 -17
  192. package/docs/ja/specdojo/recipes/stsd-recipe.md +100 -62
  193. package/docs/ja/specdojo/recipes/sysd-critical-flows-recipe.md +106 -0
  194. package/docs/ja/specdojo/recipes/sysd-cross-cutting-policy-recipe.md +137 -0
  195. package/docs/ja/specdojo/recipes/sysd-index-recipe.md +122 -0
  196. package/docs/ja/specdojo/references/command-reference.md +146 -99
  197. package/docs/ja/specdojo/references/deliverables-reference.md +9 -4
  198. package/docs/ja/specdojo/references/directory-layout-reference.md +3 -2
  199. package/docs/ja/specdojo/references/specdojo-config-reference.md +17 -16
  200. package/docs/ja/specdojo/rulebooks/bac-rulebook.md +72 -290
  201. package/docs/ja/specdojo/rulebooks/bdd-rulebook.md +212 -79
  202. package/docs/ja/specdojo/rulebooks/bds-rulebook.md +138 -154
  203. package/docs/ja/specdojo/rulebooks/bes-index-rulebook.md +147 -59
  204. package/docs/ja/specdojo/rulebooks/bes-rulebook.md +100 -96
  205. package/docs/ja/specdojo/rulebooks/br-rulebook.md +88 -108
  206. package/docs/ja/specdojo/rulebooks/ccd-mermaid-rulebook.md +126 -211
  207. package/docs/ja/specdojo/rulebooks/cdfd-d2-rulebook.md +367 -0
  208. package/docs/ja/specdojo/rulebooks/cdfd-mermaid-rulebook.md +6 -5
  209. package/docs/ja/specdojo/rulebooks/cdfd-overview-rulebook.md +96 -100
  210. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +38 -47
  211. package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +132 -106
  212. package/docs/ja/specdojo/rulebooks/cdsd-rulebook.md +102 -68
  213. package/docs/ja/specdojo/rulebooks/cdt-rulebook.md +152 -0
  214. package/docs/ja/specdojo/rulebooks/cld-rulebook.md +9 -184
  215. package/docs/ja/specdojo/rulebooks/clis-rulebook.md +187 -0
  216. package/docs/ja/specdojo/rulebooks/cnd-rulebook.md +93 -247
  217. package/docs/ja/specdojo/rulebooks/cpd-rulebook.md +104 -241
  218. package/docs/ja/specdojo/rulebooks/cxd-rulebook.md +124 -257
  219. package/docs/ja/specdojo/rulebooks/dct-index-rulebook.md +87 -98
  220. package/docs/ja/specdojo/rulebooks/dct-rulebook.md +9 -7
  221. package/docs/ja/specdojo/rulebooks/dec-rulebook.md +2 -1
  222. package/docs/ja/specdojo/rulebooks/dss-rulebook.md +193 -0
  223. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +100 -54
  224. package/docs/ja/specdojo/rulebooks/ifd-mermaid-rulebook.md +69 -252
  225. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +91 -76
  226. package/docs/ja/specdojo/rulebooks/ifx-file-rulebook.md +252 -226
  227. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +118 -40
  228. package/docs/ja/specdojo/rulebooks/imp-business-rulebook.md +11 -11
  229. package/docs/ja/specdojo/rulebooks/imp-data-rulebook.md +9 -9
  230. package/docs/ja/specdojo/rulebooks/imp-interface-rulebook.md +4 -4
  231. package/docs/ja/specdojo/rulebooks/imp-operations-rulebook.md +11 -11
  232. package/docs/ja/specdojo/rulebooks/imp-test-rulebook.md +11 -11
  233. package/docs/ja/specdojo/rulebooks/mm-rulebook.md +4 -3
  234. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +34 -29
  235. package/docs/ja/specdojo/rulebooks/pm-change-request-log-rulebook.md +8 -8
  236. package/docs/ja/specdojo/rulebooks/pm-issue-log-rulebook.md +2 -2
  237. package/docs/ja/specdojo/rulebooks/pm-organization-rulebook.md +50 -56
  238. package/docs/ja/specdojo/rulebooks/pm-plan-rulebook.md +46 -55
  239. package/docs/ja/specdojo/rulebooks/pm-quality-management-plan-rulebook.md +57 -54
  240. package/docs/ja/specdojo/rulebooks/pm-raci-rulebook.md +50 -65
  241. package/docs/ja/specdojo/rulebooks/pm-risk-register-rulebook.md +2 -2
  242. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +70 -97
  243. package/docs/ja/specdojo/rulebooks/pr-rulebook.md +2 -1
  244. package/docs/ja/specdojo/rulebooks/prj-assumptions-constraints-dependencies-rulebook.md +47 -56
  245. package/docs/ja/specdojo/rulebooks/prj-comparison-of-alternatives-rulebook.md +61 -135
  246. package/docs/ja/specdojo/rulebooks/sf-index-rulebook.md +116 -32
  247. package/docs/ja/specdojo/rulebooks/sf-rulebook.md +118 -61
  248. package/docs/ja/specdojo/rulebooks/sld-rulebook.md +152 -57
  249. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +51 -39
  250. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +101 -46
  251. package/docs/ja/specdojo/rulebooks/sysd-critical-flows-rulebook.md +72 -329
  252. package/docs/ja/specdojo/rulebooks/sysd-cross-cutting-policy-rulebook.md +74 -263
  253. package/docs/ja/specdojo/rulebooks/sysd-index-rulebook.md +78 -195
  254. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +4 -9
  255. package/docs/ja/specdojo/rulebooks/trc-requirements-to-specs-rulebook.md +3 -4
  256. package/docs/ja/specdojo/rulebooks/trc-requirements-to-tests-rulebook.md +3 -3
  257. package/docs/ja/specdojo/rulebooks/uis-rulebook.md +140 -143
  258. package/docs/ja/specdojo/samples/bac-sample.md +106 -21
  259. package/docs/ja/specdojo/samples/bdd-sample.yaml +143 -35
  260. package/docs/ja/specdojo/samples/bds-sample.md +100 -21
  261. package/docs/ja/specdojo/samples/bes-index-sample.md +59 -20
  262. package/docs/ja/specdojo/samples/bes-sample.md +80 -21
  263. package/docs/ja/specdojo/samples/br-sample.md +68 -14
  264. package/docs/ja/specdojo/samples/ccd-sample.md +81 -19
  265. package/docs/ja/specdojo/samples/cdfd-overview-sample.md +248 -140
  266. package/docs/ja/specdojo/samples/cdfd-sample.md +172 -99
  267. package/docs/ja/specdojo/samples/cdfd-uc-sample.md +130 -97
  268. package/docs/ja/specdojo/samples/cdsd-sample.md +89 -20
  269. package/docs/ja/specdojo/samples/cdt-sample.md +116 -0
  270. package/docs/ja/specdojo/samples/cld-sample.md +3 -30
  271. package/docs/ja/specdojo/samples/clis-sample.md +132 -0
  272. package/docs/ja/specdojo/samples/cnd-sample.md +127 -21
  273. package/docs/ja/specdojo/samples/cpd-sample.md +136 -22
  274. package/docs/ja/specdojo/samples/cxd-sample.md +108 -22
  275. package/docs/ja/specdojo/samples/dct-index-sample.yaml +63 -17
  276. package/docs/ja/specdojo/samples/dss-sample.md +175 -0
  277. package/docs/ja/specdojo/samples/gl-sample.yaml +50 -14
  278. package/docs/ja/specdojo/samples/ifd-sample.md +105 -21
  279. package/docs/ja/specdojo/samples/ifx-cmd-sample.yaml +91 -60
  280. package/docs/ja/specdojo/samples/ifx-file-sample.md +462 -21
  281. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +87 -19
  282. package/docs/ja/specdojo/samples/pm-members-sample.yaml +37 -13
  283. package/docs/ja/specdojo/samples/pm-organization-sample.md +52 -20
  284. package/docs/ja/specdojo/samples/pm-plan-sample.md +84 -26
  285. package/docs/ja/specdojo/samples/pm-quality-management-plan-sample.md +55 -22
  286. package/docs/ja/specdojo/samples/pm-raci-sample.md +69 -28
  287. package/docs/ja/specdojo/samples/pm-roles-sample.yaml +13 -12
  288. package/docs/ja/specdojo/samples/prj-assumptions-constraints-dependencies-sample.md +50 -26
  289. package/docs/ja/specdojo/samples/prj-comparison-of-alternatives-sample.md +89 -62
  290. package/docs/ja/specdojo/samples/sf-index-sample.md +89 -20
  291. package/docs/ja/specdojo/samples/sf-sample.md +121 -21
  292. package/docs/ja/specdojo/samples/sld-sample.md +107 -21
  293. package/docs/ja/specdojo/samples/stsd-sample.md +54 -26
  294. package/docs/ja/specdojo/samples/sysd-critical-flows-sample.md +166 -21
  295. package/docs/ja/specdojo/samples/sysd-cross-cutting-policy-sample.md +178 -21
  296. package/docs/ja/specdojo/samples/sysd-index-sample.md +82 -21
  297. package/docs/ja/specdojo/samples/tml-sample.yaml +4 -1
  298. package/docs/ja/specdojo/samples/uis-sample.md +164 -20
  299. package/docs/ja/specdojo/standards/document-metadata-standard.md +33 -4
  300. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +3 -1
  301. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +1 -0
  302. package/docs/ja/specdojo/templates/bac-template.md +76 -0
  303. package/docs/ja/specdojo/templates/bes-template.md +56 -0
  304. package/docs/ja/specdojo/templates/br-template.md +64 -0
  305. package/docs/ja/specdojo/templates/cdfd-overview-template.md +161 -83
  306. package/docs/ja/specdojo/templates/cdfd-template.md +81 -54
  307. package/docs/ja/specdojo/templates/cdfd-uc-template.md +130 -89
  308. package/docs/ja/specdojo/templates/cnd-template.md +137 -0
  309. package/docs/ja/specdojo/templates/cpd-template.md +129 -0
  310. package/docs/ja/specdojo/templates/cxd-template.md +105 -0
  311. package/docs/ja/specdojo/templates/dct-data-model-cdt-template.yaml +40 -0
  312. package/docs/ja/specdojo/templates/dct-data-model-cld-template.yaml +7 -14
  313. package/docs/ja/specdojo/templates/dct-index-template.md +9 -20
  314. package/docs/ja/specdojo/templates/dct-project-management-template.yaml +5 -1
  315. package/docs/ja/specdojo/templates/ifd-template.md +86 -0
  316. package/docs/ja/specdojo/templates/ifx-cmd-template.yaml +44 -28
  317. package/docs/ja/specdojo/templates/ifx-index-template.yaml +40 -0
  318. package/docs/ja/specdojo/templates/opr-template.md +2 -4
  319. package/docs/ja/specdojo/templates/pm-organization-template.md +9 -3
  320. package/docs/ja/specdojo/templates/pm-plan-template.md +4 -4
  321. package/docs/ja/specdojo/templates/pm-quality-management-plan-template.md +17 -9
  322. package/docs/ja/specdojo/templates/pm-raci-template.md +24 -13
  323. package/docs/ja/specdojo/templates/pm-roles-template.yaml +3 -2
  324. package/docs/ja/specdojo/templates/prj-assumptions-constraints-dependencies-template.md +6 -3
  325. package/docs/ja/specdojo/templates/prj-comparison-of-alternatives-template.md +22 -19
  326. package/docs/ja/specdojo/templates/stsd-template.md +46 -21
  327. package/docs/ja/specdojo/templates/sysd-critical-flows-template.md +94 -0
  328. package/docs/ja/specdojo/templates/sysd-cross-cutting-policy-template.md +122 -0
  329. package/docs/ja/specdojo/templates/sysd-index-template.md +89 -0
  330. package/docs/specdojo/lib/yaml-metadata.cjs +7 -0
  331. package/docs/specdojo/schemas/v1/bdd.schema.yaml +25 -57
  332. package/docs/specdojo/schemas/v1/condense-records.schema.yaml +26 -0
  333. package/docs/specdojo/schemas/v1/dct.schema.yaml +10 -0
  334. package/docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml +3 -0
  335. package/docs/specdojo/schemas/v1/esil.schema.yaml +7 -141
  336. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +3 -0
  337. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +54 -3
  338. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +3 -0
  339. package/docs/specdojo/schemas/v1/exec-plan-frontmatter.schema.yaml +14 -0
  340. package/docs/specdojo/schemas/v1/exec-result-frontmatter.schema.yaml +18 -0
  341. package/docs/specdojo/schemas/v1/finding-cause.schema.yaml +22 -0
  342. package/docs/specdojo/schemas/v1/grade-pipeline-state.schema.yaml +1 -1
  343. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +2 -0
  344. package/docs/specdojo/schemas/v1/ifx-cmd.schema.yaml +65 -5
  345. package/docs/specdojo/schemas/v1/ifx-index.schema.yaml +142 -0
  346. package/docs/specdojo/schemas/v1/register-events.schema.yaml +2 -0
  347. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +17 -1
  348. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +1 -0
  349. package/package.json +6 -3
  350. package/templates/antigravity/README.md +19 -46
  351. package/templates/antigravity/exec-defaults-snippet.yaml +5 -6
  352. package/templates/antigravity/orchestrator.md +3 -2
  353. package/templates/antigravity/settings.edit.json +73 -0
  354. package/templates/antigravity/settings.orchestrator.json +15 -0
  355. package/templates/antigravity/settings.report.json +7 -0
  356. package/templates/antigravity/settings.review.json +7 -0
  357. package/templates/claude/agents/specdojo-orchestrator.md +3 -2
  358. package/templates/codex/agents/specdojo-orchestrator.toml +3 -2
  359. package/templates/codex/orchestrator.md +3 -2
  360. package/templates/devcontainer/remote-host/devcontainer-tmux.sh +217 -0
  361. package/templates/devcontainer/remote-host/specdojo-tmux.sh.sample +8 -96
  362. package/templates/devcontainer/remote-host/ssh-config.sample +3 -1
  363. package/templates/devcontainer/tmux.conf +6 -0
  364. package/templates/init-agent-members.yaml +1 -0
  365. package/templates/init-exec-defaults.yaml +1 -1
  366. package/templates/opencode/agents/specdojo-orchestrator.md +3 -2
@@ -3,310 +3,336 @@ specdojo:
3
3
  id: specdojo:ifx-file-rulebook
4
4
  type: rulebook
5
5
  deliverable_type: api
6
- status: draft
6
+ status: ready
7
+ target_format: yaml
7
8
  recipe: not-needed
8
9
  sample: specdojo:ifx-file-sample
9
10
  template: not-needed
11
+ based_on:
12
+ - specdojo:rulebook-authoring-standard
10
13
  ---
11
14
 
12
- # 外部ファイル連携仕様(External File Exchange Specification: EFES)作成ルール
15
+ # 外部ファイル連携仕様作成ルール
13
16
 
14
- 外部システム(仕入先、物流、会計など)と **ファイル連携**するために、ファイルの形式・項目・制約・受け渡し手順を定義します。
17
+ External File Exchange Specification Authoring Rulebook
15
18
 
16
- EFES は ESIL(外部システムIF一覧)から参照される「詳細仕様」です。
17
- ESIL 側の `spec_ref: ifx-file-...` は、このEFESのID(およびファイル名)と対応させます。
19
+ 外部システムや独立したサブシステム・プロセス間でファイルを授受する契約(配置場所・命名規則・データ形式・必須項目・書き手と読み手・受け渡し手段・失敗時の扱い)を YAML 形式で定義するための規約を定めます。実装コードや外部スキーマの詳細構造は正本を参照し、本書ではファイル受け渡し契約の必須構造と判断基準を規定します。
18
20
 
19
- この章では **表ではなく YAML 1ファイル**で EFES を管理します。
21
+ ## 1. 全体方針
20
22
 
21
- 対応フォーマット:
23
+ ### 1.1. 目的と適用範囲
22
24
 
23
- - **CSV / TSV**
24
- - **JSON**
25
- - **XML**
25
+ 1. **目的**: システム間・プロセス間で授受されるデータファイルおよび状態ファイルの契約を YAML 1 ファイルで明確化し、書き手(送信元)と読み手(受信先)の認識齟齬および異常時の対応漏れを防ぎます。
26
+ 2. **適用範囲**: CSV、TSV、JSON、XML 等のファイルを介して行われるバッチ連携、データ受け渡し、および実行パイプライン段間のエビデンス・状態ファイル連携仕様に適用します。
27
+ 3. **完成例の扱い**: 本書には完成例の章や同梱 `sample` / `recipe` / `template` へのリンクを置かず、Frontmatter の `sample` 宣言で対応付けます。なお、成果物や完成例の本文から他仕様(一覧や関連契約)を参照することは妨げません。
26
28
 
27
- ## 1. ファイル規約
29
+ ### 1.2. 記載原則と責務境界
28
30
 
29
- - ファイル名: `ifx-file-<短い英小文字ハイフン>.yaml`
30
- - ESILからの参照: `spec_ref: ifx-file-...`(例: `ifx-file-orders`)
31
- - 1ファイル = 1つのファイル連携仕様(1つの連携ファイル、または同一契約での複数ファイル群)
31
+ 1. **外部合意に必要な最小十分の記載**: 読み手・書き手間の契約合意と検証に必要な項目に集中し、DB 物理テーブル名や内部実装クラス名などの内部構造は記載しません。
32
+ 2. **他の外部インターフェース仕様との境界**:
33
+ - ネットワーク越しの同期 API 契約は [[specdojo:ifx-api-rulebook|外部API仕様作成ルール]]、外部 CLI プロセスの起動契約(引数・標準入出力・終了コード)は [[specdojo:ifx-cmd-rulebook|外部コマンド連携仕様作成ルール]] で扱います。
34
+ - 外部コマンドやエージェントが生成・参照するファイル自体の永続化契約・必須項目・破損時の扱いを独立して合意・検証する必要がある場合は、本ルール(`ifx-file`)で定義します。
35
+ 3. **正本の参照と二重管理の防止**: データ構造の完全な定義が外部スキーマ(JSON Schema、XSD 等)や実装コードの型定義に存在する場合は、`schema_ref` または `schema.references` で正本を参照し、全項目の再掲を避けます。
32
36
 
33
- ## 2. 記載方針(必須)
37
+ ### 1.3. 対象者と確認する内容
34
38
 
35
- - **外部との合意に必要な最小十分**を記載する(内部実装の都合は書かない)
36
- - 実ファイルの「**生成/受領の責任境界**」が分かるようにする(送信者/受信者/方向)
37
- - 「どこに置くか/どう受け渡すか」(SFTP/共有ストレージ等)は **概要レベル**に留める
38
- - フォーマットの差異(CSV/TSV/JSON/XML)に応じて、**検証可能な構造定義**を置く
39
- - **メタ情報は `x-spec-meta` に集約**し、トレーサビリティを確保する
40
- - 仕様ファイル(このYAML)のキーは snake_case を用いる
39
+ | 対象者 | 解決する課題 | 確認・合意する内容 |
40
+ | -------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------- |
41
+ | 業務分析担当(BA)・プロダクトオーナー(PO) | 連携目的や異常時の業務継続可否を判断できない | 対象データ範囲、送信元・受信先の責任分界、欠落・遅延時の業務代替手段と公開可否 |
42
+ | アーキテクト(ARC) | 一覧・他契約との重複や競合書き込みリスクが生じる | `ifx-index` との対応、伝送手段、`atomic_write` 等の技術制約、正本スキーマとの責務分離 |
43
+ | 開発者(DEV) | 生成・読取・検証ロジックの実装条件が定まらない | 配置場所、命名規則、文字コード・改行コード、必須項目、パース失敗・I/O 異常時の分岐動作 |
44
+ | 品質保証担当(QE)・運用担当(OPS) | 異常時の合否判定と復旧手順を確認できない | 正常受領条件、`missing` / `malformed` / `transport_failure` の検知基準と退避・再実行手順 |
41
45
 
42
- 禁止(書かない):
46
+ ## 2. 位置づけと用語定義
43
47
 
44
- - DB物理テーブル名・物理カラム名・SQL全文
45
- - 実装クラス/関数名・内部モジュール構成
46
- - UI操作の逐語列挙
48
+ ### 2.1. 外部システムI/F一覧および関連仕様との関係
47
49
 
48
- ## 3. 必須構造(EFES YAML)
50
+ ```mermaid
51
+ flowchart LR
52
+ ESIL["外部システムI/F一覧 (ifx-index)"] -->|"spec_ref で参照"| EFES["外部ファイル連携仕様 (ifx-file-*)"]
53
+ IFXCMD["外部コマンド連携仕様 (ifx-cmd-*)"] -.->|"受け渡しファイル契約を参照"| EFES
54
+ EFES -->|"schema_ref / references で参照"| SCHEMA["正本スキーマ / 型定義"]
55
+ ```
49
56
 
50
- 最低限、以下を必ず含めます。
57
+ 1. **一覧からの詳細化**: 本仕様は [[specdojo:ifx-index-rulebook|外部システムI/F一覧作成ルール]] に従う `ifx-index` に登録されたファイル連携(`kind: ファイル`、または外部コマンド連携等で授受するファイル契約)の詳細仕様として位置づけます。
58
+ 2. **ID の対応**: `ifx-index` 側の `spec_ref` に記載された文書 ID(例: `prj-0001:ifx-file-agent-evidence`)と、本仕様の `x-spec-meta.id` を一致させます。
51
59
 
52
- - `x-spec-meta`(`id`, `type`, `status` を含む)
53
- - `file`(ファイル名/拡張子/命名規則)
54
- - `direction`(連携方向)
55
- - `format`(`CSV`/`TSV`/`JSON`/`XML`)
56
- - `transport`(受け渡し方法の概要)
57
- - `schema`(フォーマット別の構造定義)
60
+ ### 2.2. 用語定義
58
61
 
59
- ## 3.1 メタ情報(x-spec-meta)
62
+ | 用語 | 本書での意味 |
63
+ | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
64
+ | `source`(送信元・生成元) | 連携契約においてファイルを生成・提供する側のシステム、コンポーネント、またはロール |
65
+ | `target`(受信先・利用先) | 連携契約においてファイルを受領・消費する側のシステム、コンポーネント、またはロール |
66
+ | `writer`(書込主体) | 個別ファイルを実際に作成・更新する主体および書き込み契機。双方向連携や複数ファイル連携でファイルごとに明示する |
67
+ | `reader`(読取主体) | 個別ファイルを実際に読み取り・検証・後続処理へ渡す主体および利用目的 |
68
+ | `direction`(連携方向) | `source` と `target` 間のデータの向き(`source_to_target` / `target_to_source` / `bidirectional`) |
69
+ | `atomic_write`(アトミック書込) | 書き込み途中の不完全なファイルが読み手に参照されることを防ぐため、一時ファイル出力後にリネーム等で置換する書き込み方式 |
60
70
 
61
- | キー | 説明 | 必須 |
62
- | -------- | ---------------------------------------------------------- | ---- |
63
- | id | ファイル仕様ID(`ifx-file-...`)、ESILの `spec_ref` と対応 | ○ |
64
- | type | `api` 固定 | ○ |
65
- | status | `draft` / `ready` / `deprecated` | ○ |
66
- | based_on | 根拠となる他仕様のIDリスト(例: `["ifx-api-auth"]`) | 任意 |
71
+ ## 3. ファイル命名・ID規則
67
72
 
68
- ## 4. 主要項目
73
+ 命名と配置の共通原則は [[specdojo:docs-structure-guide|ドキュメント構成ガイド]] に従います。
69
74
 
70
- ### 4.1 direction(連携方向)
75
+ ### 3.1. ファイル配置と命名規則
71
76
 
72
- - `source_to_target` / `target_to_source`
77
+ 1. **配置先**: プロダクト文書は `docs/ja/product/020-external-interface-specs/`、プロジェクト文書は `docs/ja/projects/<project-id>/020-external-interface-specs/` に配置します。
78
+ 2. **ファイル名**: `ifx-file-<対象データまたは連携名>.yaml`(英小文字・数字・ハイフンの kebab-case、例: `ifx-file-agent-evidence.yaml`)とします。
79
+ 3. **1 ファイルの粒度**: 原則として 1 つのファイル連携契約(1 バッチ処理または 1 パイプライン受け渡し単位)につき 1 YAML ファイルを作成します。同一契約内で連動して生成・参照される複数ファイル(例: `evidence.json` と `pipeline-state.json`)は、`files` 配列を用いて 1 ファイルにまとめて定義できます。
73
80
 
74
- ※ ESIL の `direction` と同じ語彙で揃えます。
81
+ ### 3.2. 仕様 ID 規則
75
82
 
76
- ### 4.2 format(ファイルフォーマット)
83
+ 1. **仕様 ID**: プロダクト文書は `ifx-file-<kebab-case>`、プロジェクト修飾を伴う場合は `<project-id>:ifx-file-<kebab-case>` とします。
84
+ 2. **一意性**: ファイル名の stem(拡張子を除いた部分)と ID のローカル部を一致させ、文書インデックス全体で一意にします。
77
85
 
78
- - `CSV` / `TSV` / `JSON` / `XML`
86
+ ## 4. 推奨 Frontmatter・メタ情報項目
79
87
 
80
- ### 4.3 transport(受け渡し方法)
88
+ 共通メタ情報の原則とライフサイクル管理は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] を正本とします。
81
89
 
82
- 手段は実環境で変わりやすいため、仕様では以下を最低限にします。
90
+ ### 4.1. スキーマ宣言とメタ情報(x-spec-meta)の構成
83
91
 
84
- - `method`: `SFTP` / `HTTPS` / `共有ストレージ` / `その他` / `TBD`
85
- - `endpoint`: 接続先の説明(URL/ホスト名/共有パス等。機密値は書かない)
92
+ YAML 成果物の先頭にはスキーマ検証用の modeline コメント(専用スキーマが未整備の場合は `# specdojo-schema: none reason=no-ifx-file-schema`)を記載し、ルートキー `x-spec-meta` 配下にメタ情報を定義します。
86
93
 
87
- - `frequency`: 連携頻度(例: 日次 02:00、都度、手動)
94
+ ```yaml
95
+ # specdojo-schema: none reason=no-ifx-file-schema
96
+ x-spec-meta:
97
+ id: prj-0001:ifx-file-agent-evidence
98
+ type: api
99
+ status: draft
100
+ title: 外部ファイル連携仕様(agent の evidence)
101
+ rulebook: specdojo:ifx-file-rulebook
102
+ based_on:
103
+ - prj-0001:ifx-index
104
+ ```
88
105
 
89
- ## 5. schema(フォーマット別の構造定義)
106
+ ### 4.2. メタ情報の各フィールド定義
90
107
 
91
- EFES は「構造定義」を機械判読可能にするため、以下のいずれか(または両方)を採用します。
108
+ | フィールド名 | 必須 | 型 | 説明 |
109
+ | ------------ | ---- | ------ | -------------------------------------------------------------------------------------------------------------- |
110
+ | `id` | ○ | string | 仕様の一意な ID。ファイル名および `ifx-index` の `spec_ref` と対応させます。 |
111
+ | `type` | ○ | string | `api` 固定。本 rulebook の `deliverable_type: api` と一致させます(`file` 等の別値を指定してはなりません)。 |
112
+ | `status` | ○ | string | 文書のライフサイクル状態(`draft` / `ready` / `deprecated`)。`ready` への昇格は人間の `PO` のみが判断します。 |
113
+ | `title` | ○ | string | 対象ファイルまたは連携契約を識別できる日本語名称。 |
114
+ | `rulebook` | ○ | string | 準拠する rulebook ID(`specdojo:ifx-file-rulebook` 固定)。 |
115
+ | `part_of` | 任意 | array | 所属する上位文書 ID の配列。 |
116
+ | `based_on` | 任意 | array | 根拠となる上位文書 ID(`ifx-index` 等)の配列。未作成の文書や無関係な ID は記載しません。 |
117
+ | `supersedes` | 任意 | array | 置き換え元の旧仕様 ID の配列。 |
92
118
 
93
- - **フィールド一覧(共通・推奨)**: `schema.fields` で項目を列挙(CSV/TSV/JSON/XMLいずれも対応)
94
- - **厳密スキーマ(任意)**:
95
- - JSON: `schema.json_schema`(JSON Schema相当をYAMLで記述、または外部参照)
96
- - XML: `schema.xsd_ref`(XSDへの参照)
119
+ - 同梱の完成例(sample)は、業務背景・運用手順・異常系リカバリの解説を伴う Markdown 文書(Frontmatter の `type: api`、`rulebook: specdojo:ifx-file-rulebook`)として構成し、その本文中に本章および第5章の必須構造を満たす YAML 定義を掲載します。
97
120
 
98
- ### 5.1 schema.fields(共通フィールド定義)
121
+ ## 5. 本文要件
99
122
 
100
- - `schema.fields` は配列
101
- - 各フィールド要素は以下を持つ
123
+ ### 5.1. トップレベル構造
102
124
 
103
- | キー | 説明 | 必須 |
104
- | ----------- | -------------------------------------------------------------------------- | ---- |
105
- | name | 項目名(snake_case推奨) | ○ |
106
- | type | `string` / `integer` / `number` / `boolean` / `date` / `datetime` / `enum` | ○ |
107
- | description | 項目説明 | 任意 |
108
- | required | 必須かどうか(true/false) | 任意 |
109
- | example | 例値 | 任意 |
110
- | constraints | 制約(min/max/pattern等。必要な範囲で) | 任意 |
111
- | enum | `type: enum` の場合の許容値 | 任意 |
112
- | mapping | フォーマット別の対応付け(CSV列名、JSONパス、XPath等) | 任意 |
125
+ YAML のルートには以下のキーを配置します。
113
126
 
114
- #### mapping の例
127
+ | キー名 | 必須 | 型 | 概要 |
128
+ | --------------------- | ---- | -------------- | ------------------------------------------------------------------------- |
129
+ | `x-spec-meta` | ○ | object | 仕様のメタ情報(第4章参照)。 |
130
+ | `file` または `files` | ○ | object / array | 単一ファイルの場合は `file`、複数ファイル群の場合は `files` で定義する。 |
131
+ | `source` | ○ | string | 送信元・生成元のシステムまたは主体。 |
132
+ | `target` | ○ | string | 受信先・利用先のシステムまたは主体。 |
133
+ | `direction` | ○ | string | 連携方向(`source_to_target` / `target_to_source` / `bidirectional`)。 |
134
+ | `format` | ○ | string | 代表データフォーマット(`CSV` / `TSV` / `JSON` / `XML` / `その他`)。 |
135
+ | `timing` | ○ | string | 連携が発生する契機・スケジュール・パイプライン段階。 |
136
+ | `transport` | ○ | object | 受け渡し手段・配置エンドポイント・頻度・書き込み安全性。 |
137
+ | `schema` | ○ | object | フォーマット別の構文設定と、フィールド定義または正本スキーマ参照。 |
138
+ | `error_handling` | ○ | object | 欠落(`missing`)・破損(`malformed`)・伝送失敗(`transport_failure`)。 |
115
139
 
116
- - CSV/TSV: `mapping.csv.column: "order_id"`(ヘッダ名)または `mapping.csv.index: 1`(1始まり)
117
- - JSON: `mapping.json.pointer: "/data/order_id"`(JSON Pointer)
118
- - XML: `mapping.xml.xpath: "/Order/OrderId"`(XPath例)
140
+ ### 5.2. ファイル基本情報(file / files)
119
141
 
120
- ### 5.2 CSV/TSV 固有
142
+ 単一ファイルの場合は `file` オブジェクト、同一契約内で複数のファイルを扱う場合は `files` 配列の各要素に以下の項目を定義します。
121
143
 
122
- `schema.csv` を定義します。
144
+ | 項目名 | 必須 | 型 | 説明 |
145
+ | ----------------- | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
146
+ | `name` | ○ | string | ファイルの基本名称(例: `orders.csv`、`evidence.json`)。 |
147
+ | `naming_rule` | ○ | string | 固定名または日時・連番・識別子を含む命名規則(例: `orders_YYYYMMDD.csv`、`evidence.json`)。 |
148
+ | `location` | ○ | string | 配置ディレクトリまたは論理パス。可変部は `<project-id>`、`<run-id>` 等のプレースホルダで示します。 |
149
+ | `description` | ○ | string | 当該ファイルが担う役割と格納データの要約。 |
150
+ | `writer` | 条件付き | string | ファイルを生成・更新する主体と書き込み契機。`files` で複数ファイルを扱う場合や `bidirectional` 連携では必須とします。 |
151
+ | `reader` | 条件付き | string | ファイルを読み取る主体と利用目的。`files` で複数ファイルを扱う場合や `bidirectional` 連携では必須とします。 |
152
+ | `format` | 任意 | string | ファイル個別のフォーマット(`files` 内で形式や文字コードを確認・明示する場合に記載)。 |
153
+ | `encoding` | 任意 | string | ファイル個別の文字エンコーディング(例: `UTF-8`)。 |
154
+ | `schema_ref` | 任意 | string | 当該ファイルの構造正本(実装型定義やスキーマファイル)への参照パス(例: `src/exec/evidence.ts#ExecEvidence`)。 |
155
+ | `required_fields` | 任意 | array | 正本参照時に読み手が必須として検証するトップレベル項目名の配列(例: `[schema_version, task_id, run_id, validations]`)。 |
123
156
 
124
- - `delimiter`: `,`(CSV)/ `\t`(TSV)
125
- - `header`: true/false
126
- - `quote`: `"` など(任意)
127
- - `encoding`: `UTF-8` 推奨
128
- - `line_ending`: `LF` 推奨(必要なら `CRLF`)
157
+ ### 5.3. 連携方向と参加者(source, target, direction)
129
158
 
130
- ### 5.3 JSON 固有
159
+ 1. `source`: ファイルを生成・出力する側のシステム名またはコンポーネント名を明記します。
160
+ 2. `target`: ファイルを受領・処理する側のシステム名またはコンポーネント名を明記します。
161
+ 3. `direction`: `source_to_target`(送信元から受信先への単方向)、`target_to_source`(受信先から送信元への単方向)、`bidirectional`(段間遷移や状態ファイル更新など双方向の授受)のいずれかを指定します。
131
162
 
132
- `schema.json` を定義します。
163
+ ### 5.4. フォーマットと連携契機(format, timing)
133
164
 
134
- - `root_type`: `object` / `array`
135
- - `content_type`: `application/json`
136
- - `json_schema`: 任意(厳密に縛る場合)
165
+ 1. `format`: `CSV`、`TSV`、`JSON`、`XML`、`その他` から指定します。
166
+ 2. `timing`: 定期バッチの実行時刻(例: `毎週日曜日 21:30`、`毎日営業終了後 21:00`)またはイベント・状態遷移の契機(例: `executor 完了直後、親検証完了時、reporter 起動前後`)を検証可能な条件として記述します。
137
167
 
138
- ### 5.4 XML 固有
168
+ ### 5.5. 受け渡し方法(transport)
139
169
 
140
- `schema.xml` を定義します。
170
+ 1. `method`(必須): `ローカルファイルシステム`、`共有ストレージ`、`SFTP`、`HTTPS`、`S3`、`その他` から受け渡し手段を指定します。
171
+ 2. `endpoint`(必須): 格納ディレクトリパス、接続先ホスト・パス、またはアップロード先 URL を記述します。認証情報や秘密鍵の値は記載しません。
172
+ 3. `frequency`(必須): 連携頻度(`都度`、`タスク実行ごとに都度`、`日次`、`週次` 等)を記述します。
173
+ 4. `atomic_write`(任意): ローカルファイルシステムや共有ストレージ等で書き込み途中の読み取り・競合を防ぐ必要がある場合、一時ファイル(`.tmp` 等)への書き込みとアトミック置換(`renameSync` 等)の方針を明記します。
141
174
 
142
- - `root_element`: ルート要素名
143
- - `namespace`: 任意
144
- - `content_type`: `application/xml`
145
- - `xsd_ref`: 任意(厳密に縛る場合。ファイル名やURLを記載)
175
+ ### 5.6. 構造定義と正本参照(schema)
146
176
 
147
- ## 6. サンプル(CSV)
177
+ フォーマット別の構文設定と、データ項目の定義または正本参照を記載します。
148
178
 
149
- ```yaml
150
- x-spec-meta:
151
- id: ifx-file-orders
152
- type: file
153
- status: draft
154
- based_on: []
179
+ 1. **フォーマット別の構文設定**:
180
+ - `schema.csv` / `schema.tsv`: `delimiter`(区切り文字)、`header`(ヘッダ行の有無, boolean)、`quote`(囲み文字)、`encoding`(原則 `UTF-8`)、`line_ending`(`LF` / `CRLF`)。
181
+ - `schema.json`: `root_type`(`object` / `array`)、`content_type`(`application/json` 等)、`encoding`(`UTF-8`)。
182
+ - `schema.xml`: `root_element`、`namespace`、`encoding`、`xsd_ref`。
183
+ 2. **項目定義(外部との合意スキーマを本仕様で直接定める場合)**:
184
+ - `schema.fields` 配列に各フィールドの `name`(必須)、`type`(必須)、`description`(必須)、`required`(必須, boolean)を定義し、必要に応じて `example`、`constraints`(`min`、`max`、`maxLength`、`pattern` 等)、`mapping`(`csv.column`、`json.pointer` 等)を記載します。
185
+ 3. **正本スキーマ・型定義参照(既存の schema やコード型定義が正本の場合)**:
186
+ - `schema.references`(または `schema.schema_ref`、`files[].schema_ref`)に正本ファイルパスを記載し、各ファイルの契約上の必須項目は `files[].required_fields` で宣言します。正本に定義済みの全フィールド構造を YAML 内へ重複転記しません。
155
187
 
156
- file:
157
- name: orders.csv
158
- naming_rule: orders_YYYYMMDD.csv
159
- description: 発注データ(仕入先へ送付)
188
+ ### 5.7. 失敗時の扱いとエラーハンドリング(`error_handling`)
160
189
 
161
- source: 受発注管理(コンテナ)
162
- target: 仕入先システム
190
+ 以下の 3 区分をすべて定義します。単一ファイル契約では各区分の直下に `action` を記述し、複数ファイル(`files`)や事象ごとに振る舞いが異なる場合は対象別のサブキー(例: `evidence_json`、`pipeline_state_json`、`io_error`)を切って `action` を記述します。
163
191
 
164
- direction: source_to_target
165
- format: CSV
192
+ 1. `missing`(ファイル欠落時): 予定時刻または所定段階にファイルが存在しない場合の検知条件、フォールバック継続か中断(`blocked` 等)かの判断、新規初期化や手動発注・再実行案内などの回復手順を規定します。
193
+ 2. `malformed`(フォーマット・スキーマ不正時): 構文解析エラー、必須項目欠落、型不正、サイズ上限超過等を検知した場合の扱い(処理停止または空フォールバック、破損ファイルの退避・保持、自動再試行の有無、引き継ぎ先)を規定します。
194
+ 3. `transport_failure`(伝送・保存失敗時): ネットワーク遮断、接続タイムアウト、ディスク容量不足、権限不足、ロック競合等の I/O 失敗時の再試行方針(間隔・上限回数)または即時異常停止(終了コード等)と復旧手順を規定します。
166
195
 
167
- timing: 発注確定時
196
+ ## 6. 記述ガイド
168
197
 
169
- transport:
170
- method: SFTP
171
- endpoint: supplier-sftp.example.com:/inbound/orders
172
- frequency: 都度
198
+ ### 6.1. ファイル基本情報と責務境界の判断基準
173
199
 
174
- schema:
175
- csv:
176
- delimiter: ","
177
- header: true
178
- quote: '"'
179
- encoding: UTF-8
180
- line_ending: LF
181
-
182
- fields:
183
- - name: order_id
184
- type: string
185
- description: 発注ID
186
- required: true
187
- example: ORD-0001
188
- mapping:
189
- csv:
190
- column: order_id
191
-
192
- - name: ordered_at
193
- type: datetime
194
- description: 発注日時(RFC3339)
195
- required: true
196
- example: 2025-12-24T12:34:56Z
197
- mapping:
198
- csv:
199
- column: ordered_at
200
-
201
- - name: total_amount
202
- type: integer
203
- description: 合計金額
204
- required: true
205
- example: 1200
206
- constraints:
207
- min: 0
208
- mapping:
209
- csv:
210
- column: total_amount
211
- ```
200
+ 1. **判断基準**: 誰がいつファイルを書き(`source` / `writer`)、誰が何のために読み(`target` / `reader`)、どこにどの名前で置かれるか(`location` / `naming_rule`)が、実装コードを見ずに特定できること。
201
+ 2. **単一ファイルと複数ファイルの使い分け**: 1 つのファイルだけで完結する連携は `file` を使い、実行エビデンス(`evidence.json`)とパイプライン状態(`pipeline-state.json`)のように同一実行単位で協調動作するファイル群は `files` 配列で定義し、ファイルごとに `writer`・`reader`・`required_fields` を明記します。
202
+ 3. **仮置き・前提条件の明記**: 通信環境や運用体制に関する前提条件、または未確定の技術判断がある場合は、YAML コメントで `# _ASSUMPTION_:` や `# _UNDECIDED_:` を付記し、解消すべき担当ロール(`ARC`、`PO` 等)を明記します。
212
203
 
213
- ## 7. サンプル(JSON)
204
+ ### 6.2. 受け渡し条件と構造定義の判断基準
214
205
 
215
- ```yaml
216
- x-spec-meta:
217
- id: ifx-file-inventory-snapshot
218
- type: file
219
- status: draft
220
- based_on: []
206
+ 1. **判断基準**: 下流の `DEV` がパーサ・バリデータ・ファイル配置処理を実装でき、`QE` が正常データと境界値・異常データのテストケースを導出できること。
207
+ 2. **インライン定義と正本参照の選択**:
208
+ - 外部取引先(問屋や外部システム)との CSV / JSON 連携など、リポジトリ内に別途スキーマ定義が存在しない場合は、`schema.fields` に型・必須性・制約(`constraints`)・マッピング(`mapping`)を具体的に記述します。
209
+ - 同一システム内のランナーとエージェント間の契約など、TypeScript 型定義や JSON Schema が正本として存在する場合は、`files[].schema_ref` および `schema.references` で正本パスを指し、`files[].required_fields` に必須キーを列挙して二重管理を防ぎます。
221
210
 
222
- file:
223
- name: inventory.json
224
- naming_rule: inventory_YYYYMMDD.json
225
- description: 在庫スナップショット
211
+ ### 6.3. 失敗時の扱いの判断基準
226
212
 
227
- source: 在庫(コンテナ)
228
- target: 物流システム
213
+ 1. **判断基準**: `missing`・`malformed`・`transport_failure` のそれぞれについて、「処理を継続するか停止するか」「既存の作業成果や破損ファイルを保持するか退避するか」「自動再試行するか人間へ引き継ぐか」が明確に判別できること。
214
+ 2. **再実行時の安全性**: 再試行や `--resume` により二重処理や成果物の消失が起きないよう、状態ファイル欠落時とエビデンス欠落時の扱いの違い(例: 初回は新規生成、`--resume` 時はエラー停止)を区別して記述します。
229
215
 
230
- direction: source_to_target
231
- format: JSON
216
+ ### 6.4. 良い例と悪い例
232
217
 
233
- timing: 日次集計後
218
+ #### 6.4.1. 良い例: 正本参照・書き手と読み手・異常時動作の明確化
219
+
220
+ ```yaml
221
+ # specdojo-schema: none reason=no-ifx-file-schema
222
+ x-spec-meta:
223
+ id: prj-0001:ifx-file-agent-evidence
224
+ type: api
225
+ status: draft
226
+ title: 外部ファイル連携仕様(agent の evidence)
227
+ rulebook: specdojo:ifx-file-rulebook
228
+ based_on:
229
+ - prj-0001:ifx-index
230
+
231
+ files:
232
+ - name: evidence.json
233
+ naming_rule: evidence.json
234
+ location: docs/ja/projects/<project-id>/execution/runs/<origin>/<item-id>/<run-id>/evidence.json
235
+ description: タスク実行における変更内容・検証結果・最終メッセージを記録する構造化エビデンス
236
+ writer: SpecDojo runner(agent の stdout から抽出・正規化して書き込み)
237
+ reader: SpecDojo runner(検証合否判定、reporter への入力、result.md 反映)
238
+ format: JSON
239
+ encoding: UTF-8
240
+ schema_ref: src/exec/evidence.ts#ExecEvidence
241
+ required_fields:
242
+ - schema_version
243
+ - task_id
244
+ - run_id
245
+ - stage
246
+ - changes
247
+ - diff_summary
248
+ - validations
249
+ - final_message
250
+
251
+ source: AI provider CLI(executor / reporter agent)および SpecDojo runner
252
+ target: SpecDojo runner および結果報告(reporter)
253
+ direction: bidirectional
254
+ format: JSON
255
+ timing: タスク実行サイクルの各段遷移時(executor 完了直後、親検証完了時、reporter 起動前後)
234
256
 
235
257
  transport:
236
- method: HTTPS
237
- endpoint: https://logistics.example.com/upload
238
- frequency: 日次 02:00
258
+ method: ローカルファイルシステム
259
+ endpoint: <executionPath>/runs/<origin>/<itemId>/<runId>/
260
+ frequency: タスク実行ごとに都度
261
+ atomic_write: 一時ファイル(.tmp)へ書き込み後に renameSync でアトミック置換を実施
239
262
 
240
263
  schema:
241
264
  json:
242
265
  root_type: object
243
266
  content_type: application/json
244
-
245
- fields:
246
- - name: snapshot_date
247
- type: date
248
- required: true
249
- example: 2025-12-24
250
- mapping:
251
- json:
252
- pointer: /snapshot_date
253
-
254
- - name: items
255
- type: string
256
- description: 明細配列(厳密に縛る場合は json_schema を使用)
257
- required: true
258
- mapping:
259
- json:
260
- pointer: /items
267
+ encoding: UTF-8
268
+ references:
269
+ evidence_spec: src/exec/evidence.ts
270
+
271
+ error_handling:
272
+ missing:
273
+ evidence_json:
274
+ action: executor 終了時に未生成の場合は構造化報告を空としてフォールバックし、終了コードと親検証で判定する
275
+ malformed:
276
+ evidence_json:
277
+ action: 解析失敗ログを出力した上で構造化報告を空として扱い、成果物の変更内容は保持して手動確認へ引き継ぐ
278
+ transport_failure:
279
+ io_error:
280
+ action: ディスク容量不足や権限エラー時は標準エラー出力に理由を出力し、即時異常停止(exit code 1)させる
261
281
  ```
262
282
 
263
- ## 8. サンプル(XML)
283
+ #### 6.4.2. 悪い例: メタ情報不整合・実装詳細の混入・曖昧な異常時処理
264
284
 
265
285
  ```yaml
266
286
  x-spec-meta:
267
- id: ifx-file-payment-result
268
- type: file
269
- status: draft
270
- based_on: []
287
+ id: ifx-file-bad-example
288
+ type: file # 禁止: deliverable_type と不整合(api 固定)
289
+ status: ready # 禁止: AI エージェントによる ready 昇格
290
+ title: 連携仕様
291
+ rulebook: specdojo:ifx-file-rulebook
271
292
 
293
+ # 禁止: source, target, timing, direction が欠落している
272
294
  file:
273
- name: payment_result.xml
274
- naming_rule: payment_result_YYYYMMDDHHmmss.xml
275
- description: 決済結果(外部→当社)
295
+ name: data.json
296
+ # 禁止: naming_rule, location, description が欠落している
297
+ query: SELECT * FROM orders WHERE status = 'DONE' # 禁止: 内部 SQL の記述
298
+ handler_class: com.example.OrderHandlerImpl # 禁止: 内部実装クラス名の記述
276
299
 
277
- source: 決済サービス
278
- target: 決済(コンテナ)
300
+ transport:
301
+ method: 適切に転送する # 禁止: 手段・endpoint・frequency が不明
279
302
 
280
- direction: target_to_source
281
- format: XML
303
+ error_handling:
304
+ action: 問題ないように処理する # 禁止: missing / malformed / transport_failure の区分と具体的な回復手順がない
305
+ ```
282
306
 
283
- timing: 決済結果通知
307
+ ## 7. 禁止事項
284
308
 
285
- transport:
286
- method: 共有ストレージ
287
- endpoint: /shared/payment/result
288
- frequency: 都度
309
+ | 禁止する記述 | 理由 |
310
+ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
311
+ | `x-spec-meta.type` に `api` 以外の値(`file` 等)を指定すること | rulebook の `deliverable_type: api` およびスキーマ検証との整合が崩れるため |
312
+ | `source`、`target`、`timing`、`direction`、または `file` 必須項目の省略 | 責任境界、連携契機、配置場所・命名規則が特定できず実装・検証不能になるため |
313
+ | `error_handling` の 3 区分(`missing` / `malformed` / `transport_failure`)省略 | 異常発生時の停止・継続判断や破損ファイルの退避・復旧手順が定まらないため |
314
+ | 正本スキーマや型定義の全文コピー&ペーストによる再掲 | 正本との二重管理になり、フィールド変更時に仕様間の不整合を引き起こすため |
315
+ | DB 物理テーブル名、SQL 文、内部クラス名などの内部実装詳細の記載 | 外部インターフェース契約と内部設計の責務境界が混同されるため |
316
+ | 接続パスワード、秘密鍵、API トークン、個人情報の実データの直接記載 | セキュリティおよび機密保護上のリスクを防ぐため |
317
+ | 「適切に処理する」「問題ないようにする」等の検証不能な曖昧表現 | `DEV` の実装分岐および `QE` の合否判定基準として機能しないため |
318
+ | 本 rulebook 本文への同梱 `sample` / `recipe` / `template` の wikilink 設置 | 対応関係は Frontmatter で宣言し、本文の自己完結性と構造標準を保つため |
289
319
 
290
- schema:
291
- xml:
292
- root_element: PaymentResult
293
- namespace: TBD
294
- content_type: application/xml
295
- xsd_ref: TBD
296
-
297
- fields:
298
- - name: payment_id
299
- type: string
300
- required: true
301
- mapping:
302
- xml:
303
- xpath: /PaymentResult/PaymentId
304
-
305
- - name: status
306
- type: enum
307
- required: true
308
- enum: [PENDING, PAID, FAILED]
309
- mapping:
310
- xml:
311
- xpath: /PaymentResult/Status
312
- ```
320
+ ## 8. 運用ルール
321
+
322
+ ### 8.1. 成果物の検証手順
323
+
324
+ 1. **構文・メタ情報・整形の検証**: 作成・更新時は Prettier による整形確認、YAML 構文および先頭 modeline(`# specdojo-schema: none reason=no-ifx-file-schema` または対象スキーマ指定)の確認、ならびに `x-spec-meta` の必須項目(`type: api`、`status: draft`、`rulebook: specdojo:ifx-file-rulebook`)を検査します。
325
+ 2. **一覧・正本・テストとの照合**: `ARC` と `DEV` は `ifx-index` の `spec_ref` および `schema_ref` / `references` の参照先パスが実在し整合していることを確認します。`QE` は `files[].required_fields` と `error_handling` の 3 区分(`missing`、`malformed`、`transport_failure`)から正常系・異常系の検証ケースを導出し、期待結果と一致することを確認します。
326
+
327
+ ### 8.2. 改訂・廃止とライフサイクル変更管理
328
+
329
+ 成果物の改訂・廃止、置き換え(`supersedes`)、非推奨化(`status: deprecated`)は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] の「文書の改訂・廃止とライフサイクル変更管理」に従い、以下の役割分担で影響を追跡します。
330
+
331
+ | Role code | 改訂・廃止時の確認対象と責務 |
332
+ | --------- | ------------------------------------------------------------------------------------------------------------------ |
333
+ | `BA` | 外部システムI/F一覧(`ifx-index`)、業務プロセス、成果物カタログの記載と対象範囲の整合を確認する |
334
+ | `ARC` | `transport` の方式・安全性、正本スキーマ参照(`schema_ref` / `references`)、関連する `ifx-cmd` との境界を確認する |
335
+ | `DEV` | ファイル生成・読取ロジック、`atomic_write` 実装、正本型定義・スキーマとの一致を確認し追従修正を行う |
336
+ | `QE` | 正常受領条件および `missing` / `malformed` / `transport_failure` の異常系テストケース・受入基準への影響を確認する |
337
+ | `PM` | 仕様変更に伴う関連成果物・スケジュールタスク・プロジェクト登録簿(PJR)の追従作業を管理する |
338
+ | `PO` | 仕様の合意確定(`status: ready` への昇格)、旧仕様の置き換え(`supersedes`)、および廃止(`deprecated`)を判断する |