specdojo 0.7.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 (337) hide show
  1. package/.github/agents/specdojo-orchestrator.md +3 -2
  2. package/CHANGELOG.md +153 -0
  3. package/dist/catalog/build.js +24 -1
  4. package/dist/catalog/plan.js +1 -1
  5. package/dist/catalog/scaffold.js +4 -1
  6. package/dist/commands/init.js +5 -1
  7. package/dist/commands/night-orchestrator.js +6 -4
  8. package/dist/dashboard/dashboard-timeline.js +18 -16
  9. package/dist/dashboard/dashboard.js +612 -259
  10. package/dist/dashboard/epic-plan.js +81 -0
  11. package/dist/dashboard/exec-records.js +16 -20
  12. package/dist/dashboard/routines.js +8 -6
  13. package/dist/dashboard/timeline-build.js +5 -9
  14. package/dist/dashboard/timeline.js +9 -4
  15. package/dist/devcontainer/scaffold.js +18 -0
  16. package/dist/docs/frontmatter-namespace.js +1 -48
  17. package/dist/docs/yaml-pages.js +125 -3
  18. package/dist/exec/agent-config.js +22 -0
  19. package/dist/exec/agent-plan.js +3 -2
  20. package/dist/exec/commands.js +69 -21
  21. package/dist/exec/commit-hook-skips.js +78 -0
  22. package/dist/exec/core.js +19 -7
  23. package/dist/exec/events.js +159 -8
  24. package/dist/exec/evidence.js +64 -16
  25. package/dist/exec/handoff.js +9 -13
  26. package/dist/exec/limit.js +1 -1
  27. package/dist/exec/mechanical-result.js +45 -0
  28. package/dist/exec/migrate-records.js +249 -0
  29. package/dist/exec/parent-validation.js +153 -12
  30. package/dist/exec/pipeline-state.js +27 -5
  31. package/dist/exec/plans-condense-findings.js +89 -0
  32. package/dist/exec/plans-core.js +24 -17
  33. package/dist/exec/plans-generation.js +48 -25
  34. package/dist/exec/plans-grade-findings.js +8 -3
  35. package/dist/exec/plans-kata-findings.js +61 -0
  36. package/dist/exec/plans-planning.js +3 -3
  37. package/dist/exec/plans-storage.js +12 -24
  38. package/dist/exec/register-resume.js +55 -56
  39. package/dist/exec/register.js +26 -22
  40. package/dist/exec/repo-integration-sync.js +8 -4
  41. package/dist/exec/repo-integration.js +21 -1
  42. package/dist/exec/reporter.js +121 -23
  43. package/dist/exec/results.js +85 -24
  44. package/dist/exec/review-completion.js +47 -0
  45. package/dist/exec/review-kata.js +109 -0
  46. package/dist/exec/run/agent-pipeline.js +75 -6
  47. package/dist/exec/run/agent.js +20 -7
  48. package/dist/exec/run/in-place.js +69 -32
  49. package/dist/exec/run/job.js +81 -24
  50. package/dist/exec/run/lifecycle-commands.js +188 -36
  51. package/dist/exec/run/mode-shared.js +11 -3
  52. package/dist/exec/run/register-command.js +6 -10
  53. package/dist/exec/run/register-core.js +20 -13
  54. package/dist/exec/run/register-mode.js +12 -12
  55. package/dist/exec/run/register-post-review.js +21 -9
  56. package/dist/exec/run/register-resume.js +28 -18
  57. package/dist/exec/run/register-state.js +10 -7
  58. package/dist/exec/run/register-worktree.js +60 -30
  59. package/dist/exec/run/schedule-mode.js +4 -4
  60. package/dist/exec/run/schedule-prepare.js +201 -59
  61. package/dist/exec/run/schedule-task.js +129 -25
  62. package/dist/exec/run/shared.js +4 -3
  63. package/dist/exec/run/trailing-records.js +35 -0
  64. package/dist/exec/run-records.js +2 -0
  65. package/dist/exec/strategy.js +1 -0
  66. package/dist/exec/trailing-records.js +242 -0
  67. package/dist/exec/trial-commands.js +3 -2
  68. package/dist/exec/validate-records-commit.js +110 -0
  69. package/dist/exec/validate-records.js +148 -0
  70. package/dist/exec/worktree-command.js +29 -16
  71. package/dist/exec/worktree-ops-commit.js +119 -48
  72. package/dist/exec/worktree-ops-lifecycle.js +77 -48
  73. package/dist/exec/worktree-ops-merge.js +13 -2
  74. package/dist/exec/worktree-ops.js +2 -2
  75. package/dist/exec/worktree.js +19 -2
  76. package/dist/grade/apply.js +32 -6
  77. package/dist/grade/command-inspect.js +2 -2
  78. package/dist/grade/command-run.js +2 -0
  79. package/dist/grade/command-shared.js +1 -1
  80. package/dist/grade/core.js +18 -5
  81. package/dist/grade/markdown.js +3 -3
  82. package/dist/grade/pipeline-state.js +15 -11
  83. package/dist/grade/plan.js +37 -17
  84. package/dist/grade/result.js +3 -3
  85. package/dist/grade/run.js +23 -3
  86. package/dist/grade/target-discovery.js +17 -4
  87. package/dist/grade/targets.js +12 -11
  88. package/dist/job/job.js +31 -17
  89. package/dist/job/noop.js +104 -0
  90. package/dist/register/core.js +2 -0
  91. package/dist/register/create-commands.js +28 -3
  92. package/dist/register/deliverable-target.js +9 -1
  93. package/dist/register/epic.js +104 -26
  94. package/dist/register/event-merge.js +3 -0
  95. package/dist/register/events.js +4 -0
  96. package/dist/register/external-project.js +3 -0
  97. package/dist/register/item.js +6 -0
  98. package/dist/register/maintenance-commands.js +4 -1
  99. package/dist/register/planning.js +7 -14
  100. package/dist/register/register.js +43 -9
  101. package/dist/register/track-domains.js +34 -0
  102. package/dist/register/track-plan.js +78 -0
  103. package/dist/register/transition-commands.js +8 -0
  104. package/dist/register/work-table.js +64 -0
  105. package/dist/review/grade.js +35 -13
  106. package/dist/routine/definition.js +4 -3
  107. package/dist/routine/failure.js +30 -0
  108. package/dist/routine/routine.js +56 -32
  109. package/dist/routine/storage.js +33 -0
  110. package/dist/schedule/schedule.js +1 -0
  111. package/dist/schedule/strategy-generate-document.js +26 -14
  112. package/dist/schedule/strategy-generate-scope.js +17 -45
  113. package/dist/schedule/strategy-generate.js +33 -3
  114. package/dist/schedule/strategy-profiles.js +86 -12
  115. package/dist/shared/agent-types.js +2 -0
  116. package/dist/shared/condense-records.js +25 -0
  117. package/dist/shared/deprecation.js +8 -0
  118. package/dist/shared/document-metadata.js +20 -0
  119. package/dist/shared/finding-cause.js +20 -0
  120. package/dist/shared/frontmatter-namespace.js +48 -0
  121. package/dist/shared/git.js +142 -15
  122. package/dist/shared/grade-result.js +17 -1
  123. package/dist/shared/local-state.js +20 -0
  124. package/dist/shared/markdownlint-config.js +8 -3
  125. package/dist/shared/plan-conventions.js +129 -0
  126. package/dist/shared/plan-templates.js +57 -41
  127. package/dist/shared/run-records.js +224 -0
  128. package/dist/shared/specdojo-config.js +39 -21
  129. package/dist/shared/text.js +65 -5
  130. package/dist/shared/timeline-index.js +2 -0
  131. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +9 -2
  132. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +4 -74
  133. package/docs/ja/specdojo/exec-templates/xep-condense-template.md +50 -0
  134. package/docs/ja/specdojo/exec-templates/xep-draft-template.md +17 -5
  135. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +16 -3
  136. package/docs/ja/specdojo/exec-templates/xep-recipe-guided-template.md +15 -5
  137. package/docs/ja/specdojo/exec-templates/xep-recipe-maintenance-template.md +6 -0
  138. package/docs/ja/specdojo/exec-templates/xep-register-template.md +1 -1
  139. package/docs/ja/specdojo/exec-templates/xep-rulebook-maintenance-template.md +6 -0
  140. package/docs/ja/specdojo/exec-templates/xep-sample-maintenance-template.md +6 -0
  141. package/docs/ja/specdojo/exec-templates/xep-template-maintenance-template.md +6 -0
  142. package/docs/ja/specdojo/exec-templates/xer-condense-template.md +25 -0
  143. package/docs/ja/specdojo/exec-templates/xp-common-conventions-template.md +50 -0
  144. package/docs/ja/specdojo/exec-templates/xrp-common-conventions-template.md +30 -0
  145. package/docs/ja/specdojo/guides/branch-workflow-guide.md +1 -1
  146. package/docs/ja/specdojo/guides/docs-editing-guide.md +12 -0
  147. package/docs/ja/specdojo/guides/docs-structure-guide.md +48 -15
  148. package/docs/ja/specdojo/guides/exec-config-guide.md +47 -16
  149. package/docs/ja/specdojo/guides/exec-operation-guide.md +53 -17
  150. package/docs/ja/specdojo/guides/exec-worktree-guide.md +20 -11
  151. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +92 -55
  152. package/docs/ja/specdojo/guides/project-move-guide.md +381 -0
  153. package/docs/ja/specdojo/guides/quick-start-guide.md +70 -14
  154. package/docs/ja/specdojo/guides/register-operation-guide.md +25 -5
  155. package/docs/ja/specdojo/guides/remote-host-development-guide.md +2 -0
  156. package/docs/ja/specdojo/guides/review-guide.md +22 -19
  157. package/docs/ja/specdojo/guides/routine-operation-guide.md +14 -8
  158. package/docs/ja/specdojo/guides/ryu-guide.md +23 -13
  159. package/docs/ja/specdojo/guides/schedule-design-guide.md +7 -4
  160. package/docs/ja/specdojo/guides/schedule-operation-guide.md +27 -3
  161. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +5 -4
  162. package/docs/ja/specdojo/guides/timeline-design-guide.md +27 -144
  163. package/docs/ja/specdojo/guides/use-case-guide.md +92 -155
  164. package/docs/ja/specdojo/recipes/bac-recipe.md +94 -0
  165. package/docs/ja/specdojo/recipes/bes-recipe.md +105 -0
  166. package/docs/ja/specdojo/recipes/br-recipe.md +84 -0
  167. package/docs/ja/specdojo/recipes/cdfd-uc-recipe.md +36 -24
  168. package/docs/ja/specdojo/recipes/cnd-recipe.md +125 -0
  169. package/docs/ja/specdojo/recipes/cpd-recipe.md +126 -0
  170. package/docs/ja/specdojo/recipes/cxd-recipe.md +145 -0
  171. package/docs/ja/specdojo/recipes/ifd-recipe.md +134 -0
  172. package/docs/ja/specdojo/recipes/ifx-cmd-recipe.md +135 -86
  173. package/docs/ja/specdojo/recipes/ifx-index-recipe.md +130 -0
  174. package/docs/ja/specdojo/recipes/pm-organization-recipe.md +29 -26
  175. package/docs/ja/specdojo/recipes/pm-plan-recipe.md +35 -26
  176. package/docs/ja/specdojo/recipes/pm-quality-management-plan-recipe.md +38 -28
  177. package/docs/ja/specdojo/recipes/pm-raci-recipe.md +39 -31
  178. package/docs/ja/specdojo/recipes/pm-roles-recipe.md +26 -28
  179. package/docs/ja/specdojo/recipes/prj-assumptions-constraints-dependencies-recipe.md +10 -8
  180. package/docs/ja/specdojo/recipes/prj-comparison-of-alternatives-recipe.md +18 -17
  181. package/docs/ja/specdojo/recipes/stsd-recipe.md +100 -62
  182. package/docs/ja/specdojo/recipes/sysd-critical-flows-recipe.md +106 -0
  183. package/docs/ja/specdojo/recipes/sysd-cross-cutting-policy-recipe.md +137 -0
  184. package/docs/ja/specdojo/recipes/sysd-index-recipe.md +122 -0
  185. package/docs/ja/specdojo/references/command-reference.md +79 -64
  186. package/docs/ja/specdojo/references/deliverables-reference.md +9 -4
  187. package/docs/ja/specdojo/references/directory-layout-reference.md +3 -2
  188. package/docs/ja/specdojo/references/specdojo-config-reference.md +17 -16
  189. package/docs/ja/specdojo/rulebooks/bac-rulebook.md +72 -290
  190. package/docs/ja/specdojo/rulebooks/bdd-rulebook.md +212 -79
  191. package/docs/ja/specdojo/rulebooks/bds-rulebook.md +138 -154
  192. package/docs/ja/specdojo/rulebooks/bes-index-rulebook.md +147 -59
  193. package/docs/ja/specdojo/rulebooks/bes-rulebook.md +100 -96
  194. package/docs/ja/specdojo/rulebooks/br-rulebook.md +88 -108
  195. package/docs/ja/specdojo/rulebooks/ccd-mermaid-rulebook.md +126 -211
  196. package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +56 -35
  197. package/docs/ja/specdojo/rulebooks/cdsd-rulebook.md +102 -68
  198. package/docs/ja/specdojo/rulebooks/cdt-rulebook.md +152 -0
  199. package/docs/ja/specdojo/rulebooks/cld-rulebook.md +9 -184
  200. package/docs/ja/specdojo/rulebooks/clis-rulebook.md +187 -0
  201. package/docs/ja/specdojo/rulebooks/cnd-rulebook.md +93 -247
  202. package/docs/ja/specdojo/rulebooks/cpd-rulebook.md +104 -241
  203. package/docs/ja/specdojo/rulebooks/cxd-rulebook.md +124 -257
  204. package/docs/ja/specdojo/rulebooks/dct-index-rulebook.md +87 -98
  205. package/docs/ja/specdojo/rulebooks/dct-rulebook.md +9 -7
  206. package/docs/ja/specdojo/rulebooks/dec-rulebook.md +2 -1
  207. package/docs/ja/specdojo/rulebooks/dss-rulebook.md +193 -0
  208. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +100 -54
  209. package/docs/ja/specdojo/rulebooks/ifd-mermaid-rulebook.md +69 -252
  210. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +91 -76
  211. package/docs/ja/specdojo/rulebooks/ifx-file-rulebook.md +252 -226
  212. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +118 -40
  213. package/docs/ja/specdojo/rulebooks/imp-business-rulebook.md +11 -11
  214. package/docs/ja/specdojo/rulebooks/imp-data-rulebook.md +9 -9
  215. package/docs/ja/specdojo/rulebooks/imp-interface-rulebook.md +4 -4
  216. package/docs/ja/specdojo/rulebooks/imp-operations-rulebook.md +11 -11
  217. package/docs/ja/specdojo/rulebooks/imp-test-rulebook.md +11 -11
  218. package/docs/ja/specdojo/rulebooks/mm-rulebook.md +4 -3
  219. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +34 -29
  220. package/docs/ja/specdojo/rulebooks/pm-change-request-log-rulebook.md +8 -8
  221. package/docs/ja/specdojo/rulebooks/pm-issue-log-rulebook.md +2 -2
  222. package/docs/ja/specdojo/rulebooks/pm-organization-rulebook.md +50 -56
  223. package/docs/ja/specdojo/rulebooks/pm-plan-rulebook.md +46 -55
  224. package/docs/ja/specdojo/rulebooks/pm-quality-management-plan-rulebook.md +57 -54
  225. package/docs/ja/specdojo/rulebooks/pm-raci-rulebook.md +50 -65
  226. package/docs/ja/specdojo/rulebooks/pm-risk-register-rulebook.md +2 -2
  227. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +70 -97
  228. package/docs/ja/specdojo/rulebooks/pr-rulebook.md +2 -1
  229. package/docs/ja/specdojo/rulebooks/prj-assumptions-constraints-dependencies-rulebook.md +47 -56
  230. package/docs/ja/specdojo/rulebooks/prj-comparison-of-alternatives-rulebook.md +61 -135
  231. package/docs/ja/specdojo/rulebooks/sf-index-rulebook.md +116 -32
  232. package/docs/ja/specdojo/rulebooks/sf-rulebook.md +118 -61
  233. package/docs/ja/specdojo/rulebooks/sld-rulebook.md +152 -57
  234. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +51 -39
  235. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +101 -46
  236. package/docs/ja/specdojo/rulebooks/sysd-critical-flows-rulebook.md +72 -329
  237. package/docs/ja/specdojo/rulebooks/sysd-cross-cutting-policy-rulebook.md +74 -263
  238. package/docs/ja/specdojo/rulebooks/sysd-index-rulebook.md +78 -195
  239. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +4 -9
  240. package/docs/ja/specdojo/rulebooks/trc-requirements-to-specs-rulebook.md +3 -4
  241. package/docs/ja/specdojo/rulebooks/trc-requirements-to-tests-rulebook.md +3 -3
  242. package/docs/ja/specdojo/rulebooks/uis-rulebook.md +140 -143
  243. package/docs/ja/specdojo/samples/bac-sample.md +106 -21
  244. package/docs/ja/specdojo/samples/bdd-sample.yaml +143 -35
  245. package/docs/ja/specdojo/samples/bds-sample.md +100 -21
  246. package/docs/ja/specdojo/samples/bes-index-sample.md +59 -20
  247. package/docs/ja/specdojo/samples/bes-sample.md +80 -21
  248. package/docs/ja/specdojo/samples/br-sample.md +68 -14
  249. package/docs/ja/specdojo/samples/ccd-sample.md +81 -19
  250. package/docs/ja/specdojo/samples/cdfd-sample.md +172 -99
  251. package/docs/ja/specdojo/samples/cdfd-uc-sample.md +9 -7
  252. package/docs/ja/specdojo/samples/cdsd-sample.md +89 -20
  253. package/docs/ja/specdojo/samples/cdt-sample.md +116 -0
  254. package/docs/ja/specdojo/samples/cld-sample.md +3 -30
  255. package/docs/ja/specdojo/samples/clis-sample.md +132 -0
  256. package/docs/ja/specdojo/samples/cnd-sample.md +127 -21
  257. package/docs/ja/specdojo/samples/cpd-sample.md +136 -22
  258. package/docs/ja/specdojo/samples/cxd-sample.md +108 -22
  259. package/docs/ja/specdojo/samples/dct-index-sample.yaml +63 -17
  260. package/docs/ja/specdojo/samples/dss-sample.md +175 -0
  261. package/docs/ja/specdojo/samples/gl-sample.yaml +50 -14
  262. package/docs/ja/specdojo/samples/ifd-sample.md +105 -21
  263. package/docs/ja/specdojo/samples/ifx-cmd-sample.yaml +91 -60
  264. package/docs/ja/specdojo/samples/ifx-file-sample.md +462 -21
  265. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +87 -19
  266. package/docs/ja/specdojo/samples/pm-members-sample.yaml +37 -13
  267. package/docs/ja/specdojo/samples/pm-organization-sample.md +52 -20
  268. package/docs/ja/specdojo/samples/pm-plan-sample.md +84 -26
  269. package/docs/ja/specdojo/samples/pm-quality-management-plan-sample.md +55 -22
  270. package/docs/ja/specdojo/samples/pm-raci-sample.md +69 -28
  271. package/docs/ja/specdojo/samples/pm-roles-sample.yaml +13 -12
  272. package/docs/ja/specdojo/samples/prj-assumptions-constraints-dependencies-sample.md +50 -26
  273. package/docs/ja/specdojo/samples/prj-comparison-of-alternatives-sample.md +89 -62
  274. package/docs/ja/specdojo/samples/sf-index-sample.md +89 -20
  275. package/docs/ja/specdojo/samples/sf-sample.md +121 -21
  276. package/docs/ja/specdojo/samples/sld-sample.md +107 -21
  277. package/docs/ja/specdojo/samples/stsd-sample.md +54 -26
  278. package/docs/ja/specdojo/samples/sysd-critical-flows-sample.md +166 -21
  279. package/docs/ja/specdojo/samples/sysd-cross-cutting-policy-sample.md +178 -21
  280. package/docs/ja/specdojo/samples/sysd-index-sample.md +82 -21
  281. package/docs/ja/specdojo/samples/tml-sample.yaml +4 -1
  282. package/docs/ja/specdojo/samples/uis-sample.md +164 -20
  283. package/docs/ja/specdojo/standards/document-metadata-standard.md +33 -4
  284. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +3 -1
  285. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +1 -0
  286. package/docs/ja/specdojo/templates/bac-template.md +76 -0
  287. package/docs/ja/specdojo/templates/bes-template.md +56 -0
  288. package/docs/ja/specdojo/templates/br-template.md +64 -0
  289. package/docs/ja/specdojo/templates/cdfd-template.md +81 -54
  290. package/docs/ja/specdojo/templates/cdfd-uc-template.md +9 -5
  291. package/docs/ja/specdojo/templates/cnd-template.md +137 -0
  292. package/docs/ja/specdojo/templates/cpd-template.md +129 -0
  293. package/docs/ja/specdojo/templates/cxd-template.md +105 -0
  294. package/docs/ja/specdojo/templates/dct-data-model-cdt-template.yaml +40 -0
  295. package/docs/ja/specdojo/templates/dct-data-model-cld-template.yaml +7 -14
  296. package/docs/ja/specdojo/templates/dct-index-template.md +9 -20
  297. package/docs/ja/specdojo/templates/dct-project-management-template.yaml +5 -1
  298. package/docs/ja/specdojo/templates/ifd-template.md +86 -0
  299. package/docs/ja/specdojo/templates/ifx-cmd-template.yaml +44 -28
  300. package/docs/ja/specdojo/templates/ifx-index-template.yaml +40 -0
  301. package/docs/ja/specdojo/templates/opr-template.md +2 -4
  302. package/docs/ja/specdojo/templates/pm-organization-template.md +9 -3
  303. package/docs/ja/specdojo/templates/pm-plan-template.md +4 -4
  304. package/docs/ja/specdojo/templates/pm-quality-management-plan-template.md +17 -9
  305. package/docs/ja/specdojo/templates/pm-raci-template.md +24 -13
  306. package/docs/ja/specdojo/templates/pm-roles-template.yaml +3 -2
  307. package/docs/ja/specdojo/templates/prj-assumptions-constraints-dependencies-template.md +6 -3
  308. package/docs/ja/specdojo/templates/prj-comparison-of-alternatives-template.md +22 -19
  309. package/docs/ja/specdojo/templates/stsd-template.md +46 -21
  310. package/docs/ja/specdojo/templates/sysd-critical-flows-template.md +94 -0
  311. package/docs/ja/specdojo/templates/sysd-cross-cutting-policy-template.md +122 -0
  312. package/docs/ja/specdojo/templates/sysd-index-template.md +89 -0
  313. package/docs/specdojo/lib/yaml-metadata.cjs +7 -0
  314. package/docs/specdojo/schemas/v1/bdd.schema.yaml +25 -57
  315. package/docs/specdojo/schemas/v1/condense-records.schema.yaml +26 -0
  316. package/docs/specdojo/schemas/v1/dct.schema.yaml +10 -0
  317. package/docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml +3 -0
  318. package/docs/specdojo/schemas/v1/esil.schema.yaml +7 -141
  319. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +3 -0
  320. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +53 -3
  321. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +3 -0
  322. package/docs/specdojo/schemas/v1/exec-plan-frontmatter.schema.yaml +14 -0
  323. package/docs/specdojo/schemas/v1/exec-result-frontmatter.schema.yaml +18 -0
  324. package/docs/specdojo/schemas/v1/finding-cause.schema.yaml +22 -0
  325. package/docs/specdojo/schemas/v1/grade-pipeline-state.schema.yaml +1 -1
  326. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +2 -0
  327. package/docs/specdojo/schemas/v1/ifx-cmd.schema.yaml +65 -5
  328. package/docs/specdojo/schemas/v1/ifx-index.schema.yaml +142 -0
  329. package/docs/specdojo/schemas/v1/register-events.schema.yaml +2 -0
  330. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +17 -1
  331. package/package.json +2 -2
  332. package/templates/antigravity/orchestrator.md +3 -2
  333. package/templates/claude/agents/specdojo-orchestrator.md +3 -2
  334. package/templates/codex/agents/specdojo-orchestrator.toml +3 -2
  335. package/templates/codex/orchestrator.md +3 -2
  336. package/templates/devcontainer/tmux.conf +6 -0
  337. package/templates/opencode/agents/specdojo-orchestrator.md +3 -2
@@ -2,37 +2,478 @@
2
2
  specdojo:
3
3
  id: specdojo:ifx-file-sample
4
4
  type: api
5
- status: draft
5
+ status: ready
6
6
  rulebook: specdojo:ifx-file-rulebook
7
+ part_of: []
8
+ based_on: []
7
9
  ---
8
10
 
9
- # [外部ファイル連携仕様](../rulebooks/ifx-file-rulebook.md) サンプル
11
+ # 駄菓子屋きぬや 外部ファイル連携仕様 サンプル
12
+
13
+ ## 1. 概要
14
+
15
+ 店主代表(`PO`)と家族利用者代表(`PO` 業務助言)が日々の店頭販売と在庫把握を行う「駄菓子屋きぬや」において、[[specdojo:ifx-file-rulebook|外部ファイル連携仕様作成ルール]] に従う 2 つの代表的なファイル受け渡し契約(**単一ファイル・インライン定義**および**複数ファイル・正本スキーマ参照**)を示す完成例である。外部取引先へ送付するバッチファイルと、店頭 CLI の実行段階間で授受・照合する状態・証跡ファイルの双方について、配置・命名・必須項目・書き手と読み手・失敗時の回復手順を検証可能な形で定義する。
16
+
17
+ _ASSUMPTION_: [[specdojo:prj-overview-sample|プロジェクト概要]] および [[specdojo:ifx-index-sample|外部システムI/F一覧]] では、初期リリースの対象を店頭販売・在庫・つけ管理とし、仕入れ先とのシステム連携は初期スコープ外としている。本書では、外部取引先との単一ファイル契約(`file` と `schema.fields`)の完成例として次期拡張候補の「週次発注 CSV 連携」を、初期スコープ内の複数ファイル協調契約(`files` と `schema_ref` / `required_fields`)の完成例として [[specdojo:clis-sample|販売管理 CLI 仕様]] の「取引状態・販売実績控え JSON 連携」を示す。ロールと体制の正本は [[specdojo:pm-roles-sample|ロール定義]] および [[specdojo:pm-members-sample|メンバー定義]] とする。
18
+
19
+ _UNDECIDED_: 本サンプルの仕様は学習用の完成例(`status: draft`)であり、実運用の採否、問屋側 SFTP 接続条件の確定、および `status: ready` への昇格は人間の店主代表(`PO`)が最終判断する。
20
+
21
+ ## 2. 利用目的と対象ユーザー
22
+
23
+ | 対象者(ロール) | 解決する課題・達成する結果 | 確認・合意する内容 |
24
+ | -------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
25
+ | 店主代表(`PO`)・家族利用者代表 | 発注漏れ・二重会計・通信障害時の記録消失を防ぎ、店番を引き継ぐ | 連携タイミング、欠落・送信失敗・破損時の店頭代替手順(電話確認・保留照合)、公開採否 |
26
+ | 技術メンター(`ARC`) | 一覧・CLI 仕様・正本スキーマとの重複や競合書き込みリスクを防ぐ | `ifx-index` との対応、`atomic_write` 方式、`schema_ref` による正本分離、責務境界 |
27
+ | 開発担当(`DEV` / `BA` / `PM`) | ファイル生成・読取・検証・退避ロジックを実装し、残課題を管理する | 配置パス、`naming_rule`、文字コード・改行、必須項目、異常時の終了コードと Schedule / PJR |
28
+ | 同行レビュー担当(`QE`) | 正常系・境界値・異常系の受入判定と回復手順が検証可能か確認する | `required_fields`、`constraints`、`missing` / `malformed` / `transport_failure` の期待値 |
29
+
30
+ CLI の対話操作と終了コード体系は [[specdojo:clis-sample|販売管理 CLI 仕様]]、外部印刷コマンド(`receipt-print`)の起動と印字用テキスト(`receipts/receipt-YYYYMMDD-NNNN.txt`)の入力契約は [[specdojo:ifx-cmd-sample|レシート印刷コマンド連携仕様]]、外部 I/F 全体の一覧は [[specdojo:ifx-index-sample|外部システムI/F一覧]] を正本とし、本書はファイル自体の永続化・受け渡し契約を扱う。
31
+
32
+ ## 3. 外部ファイル連携仕様(YAML 完成例)
33
+
34
+ ### 3.1. 単一ファイル・インライン定義の例(週次発注 CSV 連携)
35
+
36
+ リポジトリ内に別途スキーマ定義が存在しない外部取引先との単一ファイル連携では、`file` オブジェクトに基本情報と `writer` / `reader` を記載し、`schema.csv` と `schema.fields` に型・必須性・制約(`constraints`)・列マッピング(`mapping.csv.column`)を直接定義する。
37
+
38
+ ```yaml
39
+ # specdojo-schema: none reason=no-ifx-file-schema
40
+ x-spec-meta:
41
+ id: ifx-file-kinuya-orders
42
+ type: api
43
+ status: draft
44
+ title: 駄菓子屋きぬや 週次発注データ連携仕様
45
+ rulebook: specdojo:ifx-file-rulebook
46
+ based_on:
47
+ - specdojo:prj-overview-sample
48
+
49
+ # _ASSUMPTION_: 初期リリース後の次期拡張として、店舗端末から駄菓子卸問屋(丸和商会)へ
50
+ # 週次発注データを SFTP 送付する学習用の単一ファイル契約例。
51
+ # _UNDECIDED_: 問屋側 SFTP ホストおよび受領確認(ACK)方式は未確定。技術メンター(ARC)と
52
+ # 開発担当(DEV)が接続方式を詰め、人間の店主代表(PO)が採否と ready 昇格を判断する。
53
+
54
+ file:
55
+ name: orders.csv
56
+ naming_rule: orders_YYYYMMDD.csv
57
+ location: data/outbound/orders/orders_YYYYMMDD.csv
58
+ description: 駄菓子卸問屋(丸和商会)へ週次で送付する商品別発注データ
59
+ writer: 店舗端末の発注バッチ処理(毎週日曜 21:30 に確定済み発注候補から生成)
60
+ reader: 丸和商会 発注受付システム(確定名のファイルだけを週次バッチで取り込み、翌朝配送分を出荷引当する)
61
+ format: CSV
62
+ encoding: UTF-8
63
+
64
+ source: 駄菓子屋きぬや販売管理システム
65
+ target: 丸和商会発注受付システム
66
+ direction: source_to_target
67
+ format: CSV
68
+ timing: 毎週日曜日 21:30(月曜朝配送分の問屋締め切り 22:00 前)
69
+
70
+ transport:
71
+ method: SFTP
72
+ endpoint: sftp.maruwa-dagashi.example.com:/inbound/orders/
73
+ frequency: 週次
74
+ atomic_write: >-
75
+ 生成時は data/outbound/orders/ に orders_YYYYMMDD.csv.tmp を書き出してから orders_YYYYMMDD.csv へリネームして確定する。
76
+ 転送時は店舗端末が同名の .tmp を送り、送信完了後に SFTP の rename で問屋側の orders_YYYYMMDD.csv へ置き換える。
77
+ リネーム済みの確定ファイルの存在を生成完了・転送完了とみなし、別の完了フラグは置かない。
78
+
79
+ schema:
80
+ csv:
81
+ delimiter: ","
82
+ header: true
83
+ quote: '"'
84
+ encoding: UTF-8
85
+ line_ending: CRLF
86
+
87
+ fields:
88
+ - name: store_code
89
+ type: string
90
+ description: 店舗コード(きぬやは固定値 KINUYA-01。他の値は受け付けない)
91
+ required: true
92
+ example: "KINUYA-01"
93
+ constraints:
94
+ pattern: "^KINUYA-01$"
95
+ mapping:
96
+ csv:
97
+ column: store_code
98
+
99
+ - name: order_date
100
+ type: date
101
+ description: 発注日(YYYY-MM-DD)
102
+ required: true
103
+ example: "2026-11-15"
104
+ mapping:
105
+ csv:
106
+ column: order_date
107
+
108
+ - name: product_code
109
+ type: string
110
+ description: 問屋共通商品コード(JANコードまたは問屋品番)
111
+ required: true
112
+ example: "4901234567890"
113
+ constraints:
114
+ maxLength: 14
115
+ mapping:
116
+ csv:
117
+ column: product_code
118
+
119
+ - name: order_unit
120
+ type: string
121
+ description: >-
122
+ 発注単位。丸和商会の商品マスタで product_code ごとに登録された発注単位と一致させる
123
+ (BALL はボール、BOX は箱)。不一致の行は数量を換算せず malformed とする。
124
+ required: true
125
+ example: "BOX"
126
+ constraints:
127
+ enum: [BALL, BOX]
128
+ mapping:
129
+ csv:
130
+ column: order_unit
131
+
132
+ - name: order_quantity
133
+ type: integer
134
+ description: 発注数量(order_unit で示す単位の個数。例は箱 5 個)
135
+ required: true
136
+ example: 5
137
+ constraints:
138
+ min: 1
139
+ max: 999
140
+ mapping:
141
+ csv:
142
+ column: order_quantity
143
+
144
+ error_handling:
145
+ missing:
146
+ action: >-
147
+ 日曜 21:45 時点で確定ファイル orders_YYYYMMDD.csv(.tmp ではないもの)が存在しない場合、
148
+ 店舗端末へ未生成警告を表示し、店主代表(PO)が発注バッチを 1 回だけ手動再実行する。
149
+ 再実行後も 22:00 までに転送完了しない場合は自動送信を止め、transport_failure の 22:00 以降の手順に従う。
150
+ malformed:
151
+ action: >-
152
+ 必須列の欠落、文字コード不正、constraints 違反、または order_unit と商品マスタの発注単位の不一致を
153
+ 検知した場合は SFTP 送信を中止し、
154
+ 対象ファイルを data/quarantine/ へ隔離して前回確定済み控えを保持したまま開発担当(DEV)へ通知する。
155
+ transport_failure:
156
+ action: >-
157
+ 問屋側は確定名の orders_YYYYMMDD.csv だけを取り込み、.tmp は取り込まない。確定名は rename でだけ現れるので、
158
+ rename 要求を出す前の失敗(接続・ログインの失敗、.tmp の転送中の失敗)は「未着の確定」とする。
159
+ 未着の確定なら送信待ちキュー(data/outbound/orders/)に保持したまま、5 分間隔で最大 3 回再試行する。
160
+ rename 要求を出した後に完了応答を得られない場合は、届いたかどうかを「不明」とし、自動再送を止める。
161
+ 問屋側は取込後に確定ファイルを移動・削除することがあるので、一覧に確定名がないことを未着の根拠にしない。
162
+ 22:00 までに完了しない場合も自動再送を止める。すべての試行が未着の確定なら店主代表(PO)が電話発注し、
163
+ CSV を data/outbound/orders/phoned/ へ移して後から自動送信しない。
164
+ 不明の場合は電話発注の前に、PO が問屋へ CSV の受領有無を電話で確認する。受領済みなら電話発注せず CSV を
165
+ data/outbound/orders/sent/ へ移す。未受領、または問屋が受領した CSV の取消に応じた場合だけ電話発注し、
166
+ CSV を phoned/ へ移す。問屋が確認できない間は電話発注も再送もしない。
167
+ ```
168
+
169
+ ### 3.2. 複数ファイル・正本参照の例(取引状態・販売実績控え JSON 連携)
170
+
171
+ 同一実行サイクル内で複数の状態・証跡ファイルを協調更新し、データ構造の正本が別スキーマに存在する場合は、`files` 配列にファイルごとの `writer`・`reader`・`schema_ref`・`required_fields` を定義し、`schema.references` で正本を参照して全フィールドの再掲を避ける。
172
+
173
+ ```yaml
174
+ # specdojo-schema: none reason=no-ifx-file-schema
175
+ x-spec-meta:
176
+ id: ifx-file-kinuya-sales-evidence
177
+ type: api
178
+ status: draft
179
+ title: 駄菓子屋きぬや 取引状態・販売実績控えファイル連携仕様
180
+ rulebook: specdojo:ifx-file-rulebook
181
+ based_on:
182
+ - specdojo:clis-sample
183
+
184
+ # _ASSUMPTION_: [[specdojo:clis-sample|販売管理 CLI 仕様]] の各サブコマンド実行時に、
185
+ # 進行中の取引状態と確定後の販売実績控え(エビデンス)をローカルで授受・照合する契約例。
186
+ # CLI 内部の取引記録は外部 I/F 一覧の登録対象外のため、ifx-index の spec_ref からは参照せず、
187
+ # 販売管理 CLI 仕様の入出力表(kinuya-session-schema / kinuya-sales-record-schema)から本契約へ辿る。
188
+ # 構造の正本は店舗アプリの schemas/ 配下の JSON Schema とし、その内容例を本書「参照する正本スキーマの例と検証」に示す。
189
+ # 技術メンター(ARC)が正本分離と atomic_write 方式を管理し、PO が ready 昇格を判断する。
190
+
191
+ files:
192
+ - name: current-tx.json
193
+ naming_rule: current-tx.json
194
+ location: <store-data-dir>/.session/current-tx.json
195
+ description: >-
196
+ 進行中の現金販売取引の明細・金額集計・会計要求状態を保持し、
197
+ コマンド間での状態引き継ぎ、二重開始防止、および中断時の再開判定に用いる状態ファイル。
198
+ writer: 販売管理 CLI(sales start で新規生成、sales add / complete でアトミック更新、会計確定または open での cancel で削除)
199
+ reader: 販売管理 CLI(各サブコマンド起動時の状態検証・再開判定)および店主代表・開発担当(障害時の状態照合)
200
+ format: JSON
201
+ encoding: UTF-8
202
+ schema_ref: schemas/kinuya-session.schema.json
203
+ required_fields:
204
+ - schema_version
205
+ - tx_id
206
+ - started_at
207
+ - status
208
+ - line_items
209
+ - subtotal_yen
210
+ - tax_yen
211
+ - total_yen
212
+
213
+ - name: TX-YYYYMMDD-NNNN.json
214
+ naming_rule: TX-<YYYYMMDD>-<NNNN>.json
215
+ location: <store-data-dir>/data/sales/TX-<YYYYMMDD>-<NNNN>.json
216
+ description: >-
217
+ 会計確定要求時の販売実績明細(商品・単価・数量)と金額集計、預かり金・釣銭、本部売上登録 API の受付結果、
218
+ およびレシート印字状態を記録する証跡(エビデンス)ファイル。current-tx.json の削除後も明細の正本として残し、
219
+ 販売管理 CLI は会計確定後に削除・上書きしない(受付結果と印字状態の更新を除く)。
220
+ writer: 販売管理 CLI(sales complete の送信前に pending で新規生成し、本部受付応答受領・receipt-print 実行後にアトミック更新)
221
+ reader: 販売管理 CLI(二重送信抑止・回復照合)、店主代表(PO)・開発担当(DEV)(通信失敗・印字未完了時の照合)
222
+ format: JSON
223
+ encoding: UTF-8
224
+ schema_ref: schemas/kinuya-sales-record.schema.json
225
+ required_fields:
226
+ - schema_version
227
+ - tx_id
228
+ - business_date
229
+ - seq_no
230
+ - line_items
231
+ - subtotal_yen
232
+ - tax_yen
233
+ - total_yen
234
+ - tendered_yen
235
+ - change_yen
236
+ - api_sync_status
237
+ - print_status
238
+ - recorded_at
239
+
240
+ source: 店舗端末の販売管理 CLI(sales start / add / total / complete / cancel)
241
+ target: 店舗端末の販売管理 CLI(後続サブコマンド・回復照合処理)および店頭運用・保守確認
242
+ direction: bidirectional
243
+ format: JSON
244
+ timing: >-
245
+ 取引開始時、明細追加時、会計確定要求前後、本部売上登録応答受領時、
246
+ レシート印字完了後、および中断・障害後の再開照合時
247
+
248
+ transport:
249
+ method: ローカルファイルシステム
250
+ endpoint: <store-data-dir>/(.session/ および data/sales/)
251
+ frequency: 取引操作ごとに都度
252
+ atomic_write: >-
253
+ 各ファイルは同一ディレクトリ内の一時ファイル(.tmp)へ書き込んで fsync し、renameSync で置換した後に
254
+ ディレクトリも fsync する。sales complete は次の順に書き、前の段の永続化を確かめてから次へ進む。
255
+ (1) current-tx.json の明細と金額を写した TX-*.json を api_sync_status pending で書く。
256
+ (2) current-tx.json の status を payment_requested にする。
257
+ (3) 本部売上登録 API へ送り、応答で TX-*.json の api_sync_status を accepted / rejected / unknown にする。
258
+ rejected なら「売上登録失敗(exit code 3)」、unknown なら「売上登録結果不明(exit code 3)」で停止し、
259
+ current-tx.json と TX-*.json をどちらも保持する。(4) と (5) へは進まない。
260
+ (4) accepted の永続化を確かめた後だけ receipt-print を実行し、TX-*.json の print_status を更新する。
261
+ (5) TX-*.json が accepted で永続化されていることを確かめた場合だけ current-tx.json を削除する。
262
+ 本部へ送るのは (2) の後に限るので、status が open なら未送信と判定できる。
263
+ 途中で止まったファイルの組み合わせの扱いは本書「会計確定の書き込み順序と再開判定」に従う。
264
+
265
+ schema:
266
+ json:
267
+ root_type: object
268
+ content_type: application/json
269
+ encoding: UTF-8
270
+ references:
271
+ session_schema: schemas/kinuya-session.schema.json
272
+ sales_record_schema: schemas/kinuya-sales-record.schema.json
273
+
274
+ error_handling:
275
+ missing:
276
+ current_tx_json:
277
+ action: >-
278
+ sales start 実行時に存在しない場合は、生成の前に data/sales/ の控えを検査する。
279
+ api_sync_status が pending / unknown / rejected の控えが 1 件でもあれば生成せず、
280
+ 「売上登録結果不明(exit code 3)」で停止して店主代表(PO)と開発担当(DEV)の本部受付照合へ引き継ぐ。
281
+ 未解決の控えがない場合だけ新規取引として生成する。
282
+ sales add / total / complete / cancel 実行時に欠落している場合は「取引未開始(exit code 2)」として停止し、
283
+ 空の状態ファイルを自動生成しない。
284
+ sales_record_json:
285
+ action: >-
286
+ 会計要求後の回復照合時に該当取引の控えファイルが欠落している場合は、未登録と即断せず
287
+ current-tx.json を保持したまま「売上登録結果不明(exit code 3)」として停止し、
288
+ 店主代表(PO)と開発担当(DEV)による本部受付照会へ引き継ぐ。
289
+
290
+ malformed:
291
+ current_tx_json:
292
+ action: >-
293
+ JSON 構文不正または required_fields 欠落を検知した場合は、二重会計や明細消失を防ぐため
294
+ 「取引記録破損(exit code 2)」として即時停止し、破損ファイルを削除・強制初期化せず保持して
295
+ 店主代表(PO)と開発担当(DEV)の照合へ引き継ぐ。
296
+ sales_record_json:
297
+ action: >-
298
+ JSON 解析失敗またはスキーマ不整合を検知した場合は、自動再送や上書きを行わず
299
+ 破損ファイルを data/quarantine/ へ退避コピーしたうえで元ファイルを保持し、
300
+ 開発担当(DEV)の調査と店主代表(PO)の本部受付照合を促す。
301
+
302
+ transport_failure:
303
+ io_error:
304
+ action: >-
305
+ ディスク容量不足、書き込み権限不足、ファイルロック競合等の I/O エラー発生時は、
306
+ 標準エラー出力に対象パス・取引番号・受付状態を出力して即時異常停止(exit code 4)させ、
307
+ 確定済み売上の再登録を行わずに開発担当(DEV)の環境復旧へ引き継ぐ。
308
+ ```
309
+
310
+ ### 3.3. 参照する正本スキーマの例と検証
311
+
312
+ 「複数ファイル・正本参照の例(取引状態・販売実績控え JSON 連携)」の `schema_ref` が指す正本の内容例を示す。項目の追加・型の変更はこの正本で行い、同節の YAML には `required_fields` だけを残す。どちらも JSON Schema 2020-12 で書き、`additionalProperties: false` で未定義の項目を拒否する。
313
+
314
+ `schemas/kinuya-session.schema.json`(進行中の取引状態):
315
+
316
+ ```json
317
+ {
318
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
319
+ "$id": "kinuya-session-schema",
320
+ "type": "object",
321
+ "additionalProperties": false,
322
+ "required": [
323
+ "schema_version",
324
+ "tx_id",
325
+ "started_at",
326
+ "status",
327
+ "line_items",
328
+ "subtotal_yen",
329
+ "tax_yen",
330
+ "total_yen"
331
+ ],
332
+ "properties": {
333
+ "schema_version": { "const": 1 },
334
+ "tx_id": { "type": "string", "pattern": "^TX-\\d{8}-\\d{4}$" },
335
+ "started_at": { "type": "string", "format": "date-time" },
336
+ "status": { "enum": ["open", "payment_requested"] },
337
+ "line_items": {
338
+ "type": "array",
339
+ "items": {
340
+ "type": "object",
341
+ "additionalProperties": false,
342
+ "required": ["product_code", "product_name", "unit_price_yen", "quantity"],
343
+ "properties": {
344
+ "product_code": { "type": "string", "maxLength": 14 },
345
+ "product_name": { "type": "string", "minLength": 1 },
346
+ "unit_price_yen": { "type": "integer", "minimum": 0 },
347
+ "quantity": { "type": "integer", "minimum": 1, "maximum": 99 }
348
+ }
349
+ }
350
+ },
351
+ "subtotal_yen": { "type": "integer", "minimum": 0 },
352
+ "tax_yen": { "type": "integer", "minimum": 0 },
353
+ "total_yen": { "type": "integer", "minimum": 0 }
354
+ },
355
+ "if": { "properties": { "status": { "const": "payment_requested" } } },
356
+ "then": { "properties": { "line_items": { "minItems": 1 } } }
357
+ }
358
+ ```
359
+
360
+ `schemas/kinuya-sales-record.schema.json`(販売実績控え):
361
+
362
+ ```json
363
+ {
364
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
365
+ "$id": "kinuya-sales-record-schema",
366
+ "type": "object",
367
+ "additionalProperties": false,
368
+ "required": [
369
+ "schema_version",
370
+ "tx_id",
371
+ "business_date",
372
+ "seq_no",
373
+ "line_items",
374
+ "subtotal_yen",
375
+ "tax_yen",
376
+ "total_yen",
377
+ "tendered_yen",
378
+ "change_yen",
379
+ "api_sync_status",
380
+ "print_status",
381
+ "recorded_at"
382
+ ],
383
+ "properties": {
384
+ "schema_version": { "const": 1 },
385
+ "tx_id": { "type": "string", "pattern": "^TX-\\d{8}-\\d{4}$" },
386
+ "business_date": { "type": "string", "format": "date" },
387
+ "seq_no": { "type": "integer", "minimum": 1, "maximum": 9999 },
388
+ "line_items": {
389
+ "type": "array",
390
+ "minItems": 1,
391
+ "items": {
392
+ "type": "object",
393
+ "additionalProperties": false,
394
+ "required": ["product_code", "product_name", "unit_price_yen", "quantity"],
395
+ "properties": {
396
+ "product_code": { "type": "string", "maxLength": 14 },
397
+ "product_name": { "type": "string", "minLength": 1 },
398
+ "unit_price_yen": { "type": "integer", "minimum": 0 },
399
+ "quantity": { "type": "integer", "minimum": 1, "maximum": 99 }
400
+ }
401
+ }
402
+ },
403
+ "subtotal_yen": { "type": "integer", "minimum": 0 },
404
+ "tax_yen": { "type": "integer", "minimum": 0 },
405
+ "total_yen": { "type": "integer", "minimum": 0 },
406
+ "tendered_yen": { "type": "integer", "minimum": 0 },
407
+ "change_yen": { "type": "integer", "minimum": 0 },
408
+ "api_sync_status": { "enum": ["pending", "accepted", "rejected", "unknown"] },
409
+ "print_status": { "enum": ["not_requested", "printed", "failed", "unknown"] },
410
+ "recorded_at": { "type": "string", "format": "date-time" }
411
+ },
412
+ "if": { "properties": { "api_sync_status": { "not": { "const": "accepted" } } } },
413
+ "then": { "properties": { "print_status": { "const": "not_requested" } } }
414
+ }
415
+ ```
416
+
417
+ 状態値の意味と組み合わせは次のとおり。`current-tx.json` は会計確定(本部受付と控え保存の確認後)または `open` での取消で削除するため、`status` は未解決の 2 値だけを持つ。明細は送信前に控えの `line_items` へ写すので、`current-tx.json` の削除後も控えから品目・単価・数量を確認できる。印字は会計確定後に限るので、`api_sync_status` が `accepted` 以外なら `print_status` は `not_requested` に限る。`tendered_yen - total_yen = change_yen` の一致はスキーマで表せないため、読み手の CLI が追加で検査し、不一致は `malformed` とする。
418
+
419
+ | 項目 | 値 | 意味と扱い |
420
+ | ----------------- | --------------------------- | --------------------------------------------------------------------------------------- |
421
+ | `status` | `open` | 明細追加中。`sales add` / `total` / `cancel` を受け付ける |
422
+ | `status` | `payment_requested` | 控えを `pending` で保存した後、本部へ送る前に書く。送信済みの可能性があるため取消は不可 |
423
+ | `api_sync_status` | `pending` | 送信前に控えを保存した状態。送信済みかどうかは `current-tx.json` の `status` で判定する |
424
+ | `api_sync_status` | `accepted` | 本部が受付を返した。会計確定済みで、再送しない |
425
+ | `api_sync_status` | `rejected` | 本部が拒否を返した。未受付と確認済みで、原因を直した後だけ同じ取引を再送できる |
426
+ | `api_sync_status` | `unknown` | 接続不能・時間切れで受付結果が不明。未登録と断定せず、本部受付の照会まで保留する |
427
+ | `print_status` | `not_requested` / `printed` | 印字前、または印字完了 |
428
+ | `print_status` | `failed` / `unknown` | 印字未完了の警告。会計は維持し、保存済みレシートだけを再印刷する |
10
429
 
11
- ## 1. 目的と適用範囲
430
+ 検証は JSON Schema 2020-12 に対応したバリデータ(`format` の検査を有効にする)で、`current-tx.json` を `kinuya-session-schema`、`TX-*.json` を `kinuya-sales-record-schema` に照らして行う。`QE` は次の受入ケースで期待結果を確認する。
12
431
 
13
- 本書は、外部システムとのファイル連携をYAMLで定義するための最小サンプルである。
432
+ | ケース | 対象と入力の要点 | 期待結果 |
433
+ | ------------------ | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
434
+ | 正常(明細追加) | `current-tx.json`、`status: open`、明細 1 件、`total_yen` が明細と税の合計 | スキーマ適合。`sales add` / `total` を継続できる |
435
+ | 正常(会計確定) | `TX-*.json`、明細 1 件、`api_sync_status: accepted`、`print_status: printed`、釣銭が一致 | スキーマ適合。`current-tx.json` は削除済みで、明細は控えに残る |
436
+ | 不正(控えの明細) | `TX-*.json` から `line_items` を除く | スキーマ不適合。`malformed` として退避し照合へ引き継ぐ |
437
+ | 不正(必須欠落) | `current-tx.json` から `status` を除く | スキーマ不適合。`malformed` として「取引記録破損(exit code 2)」 |
438
+ | 不正(状態値) | `current-tx.json`、`status: completed` | スキーマ不適合(`enum` 違反)。`malformed` として扱う |
439
+ | 不正(組み合わせ) | `TX-*.json`、`api_sync_status: unknown`、`print_status: printed` | スキーマ不適合(`then` 違反)。`malformed` として退避し照合へ引き継ぐ |
440
+ | 未解決 | `TX-*.json` が `api_sync_status: unknown`、`current-tx.json` が同じ `tx_id` で `status: payment_requested` | スキーマ適合だが未解決。新規取引を始めず、本部受付の照会を待つ |
14
441
 
15
- ## 2. 入力情報
442
+ ### 3.4. 会計確定の書き込み順序と再開判定
16
443
 
17
- - 対象: 駄菓子屋の販売管理システム
18
- - 前提: プロジェクト文脈は handbook の共通方針に準拠する
19
- - 参照: `../rulebooks/ifx-file-rulebook.md`
444
+ `sales complete` の途中で止まった後、次に起動した CLI は `current-tx.json` と同じ `tx_id` の控えの組み合わせで次のように判定する。書き込み順序は「複数ファイル・正本参照の例(取引状態・販売実績控え JSON 連携)」の `atomic_write` を正とする。
20
445
 
21
- ## 3. 記述内容
446
+ | `current-tx.json` の `status` | 控えの状態 | 判定と CLI の扱い |
447
+ | ----------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
448
+ | `open` | なし | 明細追加中。通常どおり受け付ける |
449
+ | `open` | `pending` | 送信前に停止した(未送信が確定)。`sales complete` は控えを作り直して続ける。`sales add` / `cancel` は先に控えを削除してから進める |
450
+ | `payment_requested` | `pending` | 送信したかどうか不明。控えを `unknown` にして「売上登録結果不明(exit code 3)」で停止し、本部受付の照会を待つ |
451
+ | `payment_requested` | `unknown` | 本部受付の照会を待つ。照会の結果で `accepted` または `rejected` にする |
452
+ | `payment_requested` | `rejected` | 未受付が確定。原因を直した後だけ同じ `tx_id` で再送する |
453
+ | `payment_requested` | `accepted`(`print_status: not_requested`) | 印字したかどうか不明。`print_status` を `unknown` にして警告し、`current-tx.json` を削除する。再印刷は保存済みレシートだけで行う |
454
+ | `payment_requested` | `accepted`(`not_requested` 以外) | 削除の前に停止した。`current-tx.json` を削除して会計確定とする |
455
+ | `payment_requested` | なし | 書き込み順序と矛盾する。`missing` の `sales_record_json` に従い exit code 3 で停止する |
456
+ | なし | `accepted` | 会計確定済み。新規取引を受け付ける |
457
+ | なし | `pending` / `unknown` / `rejected` | 書き込み順序と矛盾する。「取引状態の欠落」の扱いに従い、本部受付と照合するまで新規取引を始めない |
22
458
 
23
- - 主な内容: ファイル形式、伝送方法、スケジュール、ファイル項目一覧
24
- - 必須観点: 対象、条件、判定基準、責任者
459
+ ## 4. 異常時の判断と利用者の次の手
25
460
 
26
- ## 4. 最小記述例
461
+ YAML 内の `error_handling` に基づき、店頭での業務継続と二重処理防止のために利用者が行う判断と回復確認を次表に整理する。
27
462
 
28
- | 項目 | 値 | 備考 |
29
- | ------------ | --------------------------------------------------------- | ------------------------------------ |
30
- | ドキュメント | [外部ファイル連携仕様](../rulebooks/ifx-file-rulebook.md) | 最小サンプル |
31
- | 目的 | 外部システムとのファイル連携をYAMLで定義する | specdojo:deliverables-reference 準拠 |
32
- | 主な内容 | ファイル形式、伝送方法、スケジュール、ファイル項目一覧 | 要点のみ記載 |
463
+ | 事象・区分 | 業務継続・再実行の判断基準 | 利用者(店主代表・家族利用者代表・開発担当)の次の手と回復確認 |
464
+ | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
465
+ | 週次発注 CSV の未生成(`missing`) | 日曜 21:45 に確定ファイルがなければ、手動再実行を 1 回だけ行う。22:00 までに転送完了しなければ転送失敗と同じ判断に移る | 店主代表(`PO`)が未生成警告を見て発注バッチを再実行し、22:00 までに送信完了しない場合は転送失敗の行に従い、確定済み発注候補の控えをもとに電話発注する |
466
+ | 週次発注 CSV の転送失敗(`transport_failure`) | rename 要求前の失敗(未着の確定)は自動再試行(5 分間隔・最大 3 回)を待つ。rename 要求後の失敗は不明として再送しない | 店主代表が Wi-Fi 通信状態を確認する。未着が確定なら電話発注する。不明なら問屋へ受領有無を確かめ、未受領か取消済みのときだけ電話発注して CSV を `phoned/` へ移し、受領済みなら `sent/` へ移す |
467
+ | 週次発注 CSV の形式不正(`malformed`) | 隔離された破損ファイルはそのまま送信せず、マスタ・数量の訂正後に再生成する | 開発担当(`DEV`)が `data/quarantine/` のログから不正行を特定・修正し、同行レビュー担当(`QE`)と再生成結果を確認する |
468
+ | 取引状態の欠落(`current_tx_json` の `missing`、「取引未開始」) | `sales start` が未解決の控えを検査し、1 件でもあれば新規取引を始めずに exit code 3 で停止する | 店番担当は `sales total` を使わずに停止し、店主代表と開発担当(`DEV`)が `data/sales/` の当日控えを確認する。未解決の控え(`api_sync_status` が `pending` / `unknown` / `rejected`)を本部受付と照合してから新規取引へ進む |
469
+ | 取引の二重開始(`current-tx.json` が既にある、「取引二重開始」) | 既存取引を解決するまで新規取引を開始しない | 店番担当が `sales total` で既存明細を確認する。`status: open` なら同じ取引を続けるか取り消し、`payment_requested` なら店主代表が本部受付と `data/sales/` の控えを照合する |
470
+ | 取引状態・販売控えの破損・保存失敗(`malformed` / `io_error`) | ファイル削除や強制再実行を禁止し、本部受付の有無を照合してから回復手段を選ぶ | 開発担当が容量・権限を復旧し、店主代表が本部受付済みか確認する。受付済みなら控えのみ回復し、未受付時のみ再登録を実施する |
33
471
 
34
- ## 5. 未解決事項
472
+ ## 5. メモ / 将来課題
35
473
 
36
- | 論点 | 処理方針 |
37
- | -------------- | ------------------------ |
38
- | 要件詳細の補強 | 実案件適用時に具体化する |
474
+ | 項目 | 未整備事項と影響 | 担当・解消条件・引き継ぎ先 |
475
+ | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
476
+ | 次期拡張(週次発注連携)の採否と契約 | 仕入れ先連携は初期スコープ外であり、問屋側の SFTP 接続条件と受領確認(ACK)仕様が未確定 | 店主代表(`PO`)が次期フェーズでの着手可否を判断し、着手決定後に `BA` と `DEV` が問屋担当者と接続・ACK 仕様を合意して [[specdojo:ifx-index-sample\|外部システムI/F一覧]] へ追加する |
477
+ | ローカル JSON スキーマ正本の配置 | 「参照する正本スキーマの例と検証」の 2 スキーマは内容例であり、店舗アプリの `schemas/` への配置と CLI 仕様の参照名との対応付けが未実施 | 開発担当(`DEV`)がその内容で正本を配置して `ARC` と `atomic_write`・型整合を照合し、同行レビュー担当(`QE`)が同節の受入ケースで検証する |
478
+ | 本部売上登録 API との回復照合接続 | `TX-YYYYMMDD-NNNN.json` の `api_sync_status` と照合する `ifx-api-kinuya-sales.yaml` の重複排除・受付照会仕様が未整備 | `ARC` と `DEV` が本部 API 契約で受付照会方式を確定し、`QE` が受付済み・未受付・結果不明の期待結果を確認するまで自動再送を行わず店頭保留運用を維持する |
479
+ | Schedule・プロジェクト登録簿への接続 | 正本スキーマ整備、本部受付照合の確認、および次期発注連携の検討課題が学習用 Schedule・プロジェクト登録簿(PJR)に未登録 | `PM`(開発担当兼務)が外部結合テスト計画の確定前に Schedule へ作業を登録し、結果不明時の二重登録リスクと次期拡張判断を PJR へ起票して `PO` の承認判断へ接続する |
@@ -1,29 +1,97 @@
1
- # specdojo-schema: none reason=not-implemented
2
-
1
+ # yaml-language-server: $schema=../../../specdojo/schemas/v1/ifx-index.schema.yaml
3
2
  id: specdojo:ifx-index-sample
4
3
  type: api
5
- title: 外部システムIF一覧(main)
6
- status: draft
4
+ title: 駄菓子屋きぬや 販売管理CLIの外部システムI/F一覧
5
+ status: ready
7
6
  rulebook: specdojo:ifx-index-rulebook
8
7
  supersedes: []
9
8
 
9
+ # _ASSUMPTION_: 単一店舗・店舗端末1台の学習用 CLI について、現金販売の
10
+ # 商品照会・売上登録・レシート印字を整理する。店番担当は店主代表または家族利用者代表。
11
+ # 通常利用のタブレット画面とは別の操作例であり、実案件で採用済みの仕様を表さない。
12
+ # 仕入先システム連携、本格会計、EC、つけ販売、キャッシュレス決済、オフライン同期は対象外。
13
+ # CLI 内部の取引記録・設定ファイルは外部 I/F とせず、CLI 仕様の入出力へ委譲する。
14
+ # 本部 API を用いる仮定は [[specdojo:clis-sample|販売管理 CLI 仕様]] と共有する。
15
+ # 管理担当は ARC(技術メンター)。DEV(開発担当)が詳細設計を主導し、ARC が助言する。
16
+ # Role と兼務の正本: [[specdojo:pm-roles-sample|ロール定義]]、
17
+ # [[specdojo:pm-members-sample|メンバー定義]]。
18
+ # 人間の PO(店主代表)が一覧の承認・保留・差し戻しと ready への昇格を判断する。
19
+ # _UNDECIDED_: 公開対象は本一覧と対応する詳細仕様の学習用文書。社外公開可否と
20
+ # 実運用の採否は PO の判断待ち。本部の契約未整備・印字実機確認待ちを解消済みとして公開しない。
21
+ # 本部の二つの詳細仕様は未同梱。spec_ref は TBD とし、未作成の参照名をコメントで区別する。
22
+
10
23
  interfaces:
11
- - name: 発注データ送信
12
- source: 受発注管理(コンテナ)
13
- target: 仕入先システム
14
- direction: source_to_target
15
- kind: ファイル
16
- format: CSV
17
- timing: 発注確定時
18
- error_handling: 異常時は再送・管理者通知
19
- spec_ref: ifx-file-orders
24
+ # 商品コードを渡し、商品名・販売単価・税区分を得る。商品マスタ自体は更新しない。
25
+ # 売上登録と同じ本部が相手でも、成功後の状態と失敗の影響が異なるため分ける。
26
+ - name: 本部商品マスタの照会
27
+ source: 店舗端末の販売管理 CLI
28
+ target: 本部の商品マスタ API
29
+ direction: bidirectional
30
+ kind: API
31
+ format: JSON
32
+ timing: 店番担当が購入明細へ商品を追加する時、明細を保存する前
33
+ error_handling: >-
34
+ 商品未登録ならコードを訂正する。接続不能・時間切れ・認証拒否なら明細を追加せず停止する。
35
+ 店番担当が接続を、開発担当が認証・権限を確認し、復旧後に同じ取引へ追加する。
36
+ spec_ref: TBD
37
+ # _TODO_: 詳細契約は未着手。DEV が `ifx-api-kinuya-products.yaml` に
38
+ # 接続・認証権限と応答の契約を定義し、ARC と契約レビューで照合する。
39
+ # BA(開発担当)が店番担当と商品・単価の照合手順を確認し、
40
+ # QE(同行レビュー担当)が商品未登録・通信失敗で明細が増えないことを確認する。
41
+ # 商品照会の外部結合テスト着手前に契約と期待結果をそろえて実在する ID へ接続する。
42
+ # そろうまでは商品追加経路の受入を保留し、PM への作業登録依頼は末尾にまとめる。
20
43
 
21
- - name: 決済依頼/結果
22
- source: 決済(コンテナ)
23
- target: 決済サービス
44
+ # 同一取引の販売実績を渡し、受付結果を受け取る。商品照会の成功は会計成功を意味しない。
45
+ - name: 本部への売上登録
46
+ source: 店舗端末の販売管理 CLI
47
+ target: 本部の売上登録 API
24
48
  direction: bidirectional
25
49
  kind: API
26
50
  format: JSON
27
- timing: 決済時
28
- error_handling: 失敗時はリトライ/保留
29
- spec_ref: ifx-api-payment
51
+ timing: 店番担当が購入明細と預かり金を確認し、会計確定を要求した時
52
+ error_handling: >-
53
+ 接続不能・時間切れ・拒否時は送信内容と受付状態を保持し、結果不明を未登録と断定しない。
54
+ 店主代表と開発担当が本部受付とローカル記録を照合し、確認できなければ保留する。
55
+ 会計・取消を繰り返さず、回復条件は詳細契約で確認する。
56
+ spec_ref: TBD
57
+ # _UNDECIDED_: 受付照会・重複排除・保存失敗後の回復方式が未決。
58
+ # DEV が ARC の助言を受けて本部側と方式を決め、`ifx-api-kinuya-sales.yaml` を作成する。
59
+ # BA が PO と取引の保留・確定の運用を、ARC・DEV が受付と回復の契約を、
60
+ # QE が受付済み・未受付・結果不明の期待結果を確認する。
61
+ # 売上登録の外部結合テスト着手前に合意を記録して実在する ID へ接続するまで、
62
+ # 当該経路の受入と実運用を保留する。PO には二重登録リスクと保留時の店頭対応を渡す。
63
+
64
+ # 保存済みレシートを渡し、印字結果を受け取る。売上の再登録は委ねない。
65
+ - name: 確定済みレシートの印字
66
+ source: 店舗端末の販売管理 CLI
67
+ target: receipt-print CLI と店舗プリンタ
68
+ direction: bidirectional
69
+ kind: コマンド
70
+ # 入力テキストと結果 JSON・診断が混在する。形式・構造の詳細は印刷契約が正本。
71
+ format: その他
72
+ timing: 会計確定と控え保存の後、印刷を要求した時。再印刷は紙面確認後に手動で要求した時
73
+ error_handling: >-
74
+ 印字失敗・結果不明なら会計を維持し、未印字の警告と控えを残す。
75
+ 自動再試行の可否は詳細仕様の送信前失敗の識別条件に従う。
76
+ 結果不明なら店番担当が紙面を確認し、必要時は保存済みレシートだけを再印刷する。
77
+ spec_ref: specdojo:ifx-cmd-sample
78
+ # 詳細契約: [[specdojo:ifx-cmd-sample|レシート印刷コマンド連携仕様]]。
79
+ # USB 直結・認証不要の仮定、OS 権限、起動制約と失敗分類は同契約に委譲する。
80
+ # _TODO_: 契約の完成例はあるが実機確認は未実施。DEV は ARC と起動・権限を照合し、
81
+ # BA は店番担当と警告・控え保持・紙面確認後の再印刷を確認する。
82
+ # QE が結果不明・二重印字と、会計・売上を再実行しないことを確認した記録を、
83
+ # 店頭試用の開始判断前に PO へ渡す。それまで印字経路の実運用の採否は保留する。
84
+
85
+ # _TODO_: 本部商品照会・売上登録の外部側確認窓口は未特定。
86
+ # BA は本部 API の契約レビュー前に商品・売上の確認先と権限の管理主体を特定し、
87
+ # DEV が接続・認証権限と受付・回復方式の確認を依頼できる状態にする。
88
+ # _TODO_: 上記3連携の残作業は学習用 Schedule・PJR に未登録。
89
+ # PM(開発担当)へ、外部結合テスト計画の確定前に、本部2契約の作成・確認と
90
+ # 印字実機確認の作業を Schedule へ登録するよう依頼する。
91
+ # 同じ時点で、本部窓口・認証権限の確認待ちによる着手遅延と、売上の結果不明による
92
+ # 二重登録リスクを PJR に登録し、商品追加・会計確定の受入への影響を PO へ報告する。
93
+ # 印字実機確認は店頭試用の開始判断の前提作業として追跡する。
94
+ # 登録後は該当コメントを実在する作業・管理レコードの参照へ付け替え、
95
+ # 担当・期日・進捗は Schedule、採否・公開判断は決定記録で管理する。
96
+ # スコープ・方式の変更時は ARC が連携名と詳細契約の対応を整理し、DEV と QE へ
97
+ # 実装・結合テスト対象の変更を渡す。PM が計画・管理記録へ接続し、PO が業務上の採否を判断する。