specdojo 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (462) hide show
  1. package/.github/agents/specdojo-orchestrator.md +7 -3
  2. package/CHANGELOG.md +217 -0
  3. package/dist/catalog/build.js +24 -1
  4. package/dist/catalog/catalog.js +16 -14
  5. package/dist/catalog/plan.js +1 -1
  6. package/dist/catalog/scaffold.js +4 -1
  7. package/dist/commands/agent.js +5 -3
  8. package/dist/commands/build.js +69 -10
  9. package/dist/commands/git.js +206 -0
  10. package/dist/commands/init.js +9 -3
  11. package/dist/commands/night-orchestrator.js +6 -4
  12. package/dist/commands/where.js +25 -0
  13. package/dist/dashboard/dashboard-timeline.js +18 -16
  14. package/dist/dashboard/dashboard.js +616 -261
  15. package/dist/dashboard/epic-plan.js +81 -0
  16. package/dist/dashboard/exec-records.js +16 -20
  17. package/dist/dashboard/routines.js +11 -12
  18. package/dist/dashboard/timeline-build.js +5 -9
  19. package/dist/dashboard/timeline.js +23 -18
  20. package/dist/devcontainer/scaffold.js +18 -0
  21. package/dist/docs/frontmatter-namespace.js +1 -48
  22. package/dist/docs/index-command.js +2 -2
  23. package/dist/docs/yaml-business-tables.js +243 -0
  24. package/dist/docs/yaml-interface-tables.js +106 -0
  25. package/dist/docs/yaml-pages-command.js +5 -3
  26. package/dist/docs/yaml-pages.js +268 -3
  27. package/dist/docs/yaml-table-shared.js +70 -0
  28. package/dist/docs/yaml-tables.js +39 -0
  29. package/dist/exec/agent-config.js +31 -0
  30. package/dist/exec/agent-plan.js +3 -2
  31. package/dist/exec/agent-protected-config.js +2 -0
  32. package/dist/exec/commands.js +100 -39
  33. package/dist/exec/commit-hook-skips.js +78 -0
  34. package/dist/exec/core.js +19 -7
  35. package/dist/exec/events.js +179 -8
  36. package/dist/exec/evidence.js +77 -19
  37. package/dist/exec/handoff.js +9 -13
  38. package/dist/exec/limit.js +1 -1
  39. package/dist/exec/mechanical-result.js +45 -0
  40. package/dist/exec/migrate-records.js +249 -0
  41. package/dist/exec/parent-validation.js +209 -15
  42. package/dist/exec/pipeline-state.js +27 -5
  43. package/dist/exec/plans-condense-findings.js +89 -0
  44. package/dist/exec/plans-core.js +45 -19
  45. package/dist/exec/plans-generation.js +52 -30
  46. package/dist/exec/plans-grade-findings.js +8 -3
  47. package/dist/exec/plans-kata-findings.js +61 -0
  48. package/dist/exec/plans-planning.js +3 -3
  49. package/dist/exec/plans-storage.js +12 -24
  50. package/dist/exec/post-integration.js +162 -0
  51. package/dist/exec/queue-command.js +166 -0
  52. package/dist/exec/queue.js +285 -0
  53. package/dist/exec/register-foreign-wait.js +84 -0
  54. package/dist/exec/register-resume.js +55 -56
  55. package/dist/exec/register.js +26 -22
  56. package/dist/exec/repo-integration-sync.js +21 -5
  57. package/dist/exec/repo-integration.js +21 -1
  58. package/dist/exec/reporter.js +121 -23
  59. package/dist/exec/results.js +106 -25
  60. package/dist/exec/review-completion.js +47 -0
  61. package/dist/exec/review-kata.js +112 -0
  62. package/dist/exec/run/agent-pipeline.js +78 -8
  63. package/dist/exec/run/agent.js +32 -13
  64. package/dist/exec/run/change-scope.js +365 -0
  65. package/dist/exec/run/deferred-cleanup.js +31 -0
  66. package/dist/exec/run/in-place.js +73 -33
  67. package/dist/exec/run/job-lock.js +66 -0
  68. package/dist/exec/run/job-sequence.js +137 -0
  69. package/dist/exec/run/job.js +135 -41
  70. package/dist/exec/run/lifecycle-commands.js +189 -37
  71. package/dist/exec/run/lock.js +22 -1
  72. package/dist/exec/run/mode-shared.js +11 -3
  73. package/dist/exec/run/register-command.js +14 -15
  74. package/dist/exec/run/register-core.js +20 -13
  75. package/dist/exec/run/register-mode.js +77 -17
  76. package/dist/exec/run/register-post-review.js +21 -9
  77. package/dist/exec/run/register-resume.js +95 -31
  78. package/dist/exec/run/register-state.js +23 -15
  79. package/dist/exec/run/register-worktree.js +184 -139
  80. package/dist/exec/run/schedule-mode.js +79 -18
  81. package/dist/exec/run/schedule-prepare.js +204 -59
  82. package/dist/exec/run/schedule-task.js +203 -49
  83. package/dist/exec/run/shared.js +9 -3
  84. package/dist/exec/run/trailing-records.js +35 -0
  85. package/dist/exec/run-records.js +2 -0
  86. package/dist/exec/schedule/schedule.js +116 -4
  87. package/dist/exec/shared.js +1 -1
  88. package/dist/exec/smoke.js +190 -0
  89. package/dist/exec/strategy.js +14 -3
  90. package/dist/exec/task-view.js +6 -4
  91. package/dist/exec/trailing-records.js +242 -0
  92. package/dist/exec/trial-commands.js +8 -4
  93. package/dist/exec/trial-core.js +6 -1
  94. package/dist/exec/validate-records-commit.js +110 -0
  95. package/dist/exec/validate-records.js +148 -0
  96. package/dist/exec/validation-metrics.js +181 -0
  97. package/dist/exec/worktree-cleanup-lock.js +26 -0
  98. package/dist/exec/worktree-command.js +38 -17
  99. package/dist/exec/worktree-ops-commit.js +119 -48
  100. package/dist/exec/worktree-ops-lifecycle.js +77 -48
  101. package/dist/exec/worktree-ops-merge.js +13 -2
  102. package/dist/exec/worktree-ops.js +2 -2
  103. package/dist/exec/worktree.js +32 -4
  104. package/dist/grade/apply.js +32 -6
  105. package/dist/grade/command-apply.js +3 -3
  106. package/dist/grade/command-inspect.js +7 -5
  107. package/dist/grade/command-plan.js +1 -1
  108. package/dist/grade/command-run.js +7 -1
  109. package/dist/grade/command-shared.js +1 -1
  110. package/dist/grade/core.js +18 -5
  111. package/dist/grade/markdown.js +3 -3
  112. package/dist/grade/pipeline-state.js +15 -11
  113. package/dist/grade/plan.js +37 -17
  114. package/dist/grade/result.js +3 -3
  115. package/dist/grade/run.js +87 -11
  116. package/dist/grade/target-discovery.js +17 -4
  117. package/dist/grade/targets.js +12 -11
  118. package/dist/job/definition.js +84 -8
  119. package/dist/job/job.js +109 -39
  120. package/dist/job/noop.js +104 -0
  121. package/dist/register/authoring-sources.js +22 -16
  122. package/dist/register/core.js +2 -0
  123. package/dist/register/create-commands.js +28 -3
  124. package/dist/register/deliverable-target.js +9 -1
  125. package/dist/register/epic.js +104 -26
  126. package/dist/register/event-merge.js +3 -0
  127. package/dist/register/events.js +4 -0
  128. package/dist/register/external-project.js +3 -0
  129. package/dist/register/item.js +6 -0
  130. package/dist/register/maintenance-commands.js +6 -3
  131. package/dist/register/planning.js +7 -14
  132. package/dist/register/register.js +74 -16
  133. package/dist/register/track-domains.js +34 -0
  134. package/dist/register/track-plan.js +78 -0
  135. package/dist/register/transition-commands.js +8 -0
  136. package/dist/register/work-table.js +64 -0
  137. package/dist/review/grade.js +35 -13
  138. package/dist/routine/definition.js +13 -3
  139. package/dist/routine/failure.js +30 -0
  140. package/dist/routine/routine.js +189 -71
  141. package/dist/routine/status.js +62 -0
  142. package/dist/routine/storage.js +33 -0
  143. package/dist/schedule/schedule.js +39 -39
  144. package/dist/schedule/strategy-generate-document.js +26 -14
  145. package/dist/schedule/strategy-generate-scope.js +17 -45
  146. package/dist/schedule/strategy-generate.js +33 -3
  147. package/dist/schedule/strategy-profiles.js +86 -12
  148. package/dist/shared/agent-types.js +7 -0
  149. package/dist/shared/condense-records.js +25 -0
  150. package/dist/shared/cross-process-lock.js +9 -1
  151. package/dist/shared/deprecation.js +8 -0
  152. package/dist/shared/dist-freshness.js +8 -2
  153. package/dist/shared/document-metadata.js +20 -0
  154. package/dist/shared/finding-cause.js +20 -0
  155. package/dist/shared/frontmatter-namespace.js +48 -0
  156. package/dist/shared/git-environment.js +2 -1
  157. package/dist/shared/git.js +186 -16
  158. package/dist/shared/grade-result.js +17 -1
  159. package/dist/shared/lefthook-scaffold.js +3 -0
  160. package/dist/shared/local-config.js +244 -0
  161. package/dist/shared/local-state.js +20 -0
  162. package/dist/shared/markdownlint-config.js +8 -3
  163. package/dist/shared/plan-conventions.js +129 -0
  164. package/dist/shared/plan-templates.js +57 -41
  165. package/dist/shared/run-records.js +224 -0
  166. package/dist/shared/specdojo-config.js +73 -41
  167. package/dist/shared/specdojo-gitignore.js +1 -0
  168. package/dist/shared/text.js +74 -6
  169. package/dist/shared/timeline-index.js +2 -0
  170. package/dist/shared/where-alias.js +13 -0
  171. package/dist/specdojo.js +4 -0
  172. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +11 -2
  173. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +4 -74
  174. package/docs/ja/specdojo/exec-templates/xep-condense-template.md +50 -0
  175. package/docs/ja/specdojo/exec-templates/xep-draft-template.md +17 -5
  176. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +16 -3
  177. package/docs/ja/specdojo/exec-templates/xep-recipe-guided-template.md +15 -5
  178. package/docs/ja/specdojo/exec-templates/xep-recipe-maintenance-template.md +6 -0
  179. package/docs/ja/specdojo/exec-templates/xep-register-template.md +1 -1
  180. package/docs/ja/specdojo/exec-templates/xep-rulebook-maintenance-template.md +6 -0
  181. package/docs/ja/specdojo/exec-templates/xep-sample-maintenance-template.md +6 -0
  182. package/docs/ja/specdojo/exec-templates/xep-template-maintenance-template.md +6 -0
  183. package/docs/ja/specdojo/exec-templates/xer-condense-template.md +25 -0
  184. package/docs/ja/specdojo/exec-templates/xp-common-conventions-template.md +50 -0
  185. package/docs/ja/specdojo/exec-templates/xrp-common-conventions-template.md +30 -0
  186. package/docs/ja/specdojo/guides/branch-workflow-guide.md +1 -1
  187. package/docs/ja/specdojo/guides/docs-editing-guide.md +12 -0
  188. package/docs/ja/specdojo/guides/docs-structure-guide.md +48 -15
  189. package/docs/ja/specdojo/guides/exec-config-guide.md +69 -19
  190. package/docs/ja/specdojo/guides/exec-operation-guide.md +97 -18
  191. package/docs/ja/specdojo/guides/exec-worktree-guide.md +20 -11
  192. package/docs/ja/specdojo/guides/job-sequence-guide.md +77 -0
  193. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +92 -55
  194. package/docs/ja/specdojo/guides/project-move-guide.md +381 -0
  195. package/docs/ja/specdojo/guides/quick-start-guide.md +73 -17
  196. package/docs/ja/specdojo/guides/register-operation-guide.md +26 -6
  197. package/docs/ja/specdojo/guides/remote-host-development-guide.md +2 -0
  198. package/docs/ja/specdojo/guides/review-guide.md +22 -19
  199. package/docs/ja/specdojo/guides/routine-operation-guide.md +23 -12
  200. package/docs/ja/specdojo/guides/ryu-guide.md +23 -13
  201. package/docs/ja/specdojo/guides/schedule-design-guide.md +27 -21
  202. package/docs/ja/specdojo/guides/schedule-operation-guide.md +27 -3
  203. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +5 -4
  204. package/docs/ja/specdojo/guides/timeline-design-guide.md +27 -144
  205. package/docs/ja/specdojo/guides/use-case-guide.md +92 -155
  206. package/docs/ja/specdojo/guides/waza-guide.md +12 -8
  207. package/docs/ja/specdojo/recipes/bac-recipe.md +111 -0
  208. package/docs/ja/specdojo/recipes/bes-recipe.md +141 -0
  209. package/docs/ja/specdojo/recipes/bps-recipe.md +88 -139
  210. package/docs/ja/specdojo/recipes/br-recipe.md +77 -0
  211. package/docs/ja/specdojo/recipes/cdfd-overview-recipe.md +97 -109
  212. package/docs/ja/specdojo/recipes/cdfd-recipe.md +85 -146
  213. package/docs/ja/specdojo/recipes/cdfd-uc-recipe.md +92 -99
  214. package/docs/ja/specdojo/recipes/cnd-recipe.md +135 -0
  215. package/docs/ja/specdojo/recipes/cpd-recipe.md +140 -0
  216. package/docs/ja/specdojo/recipes/cxd-recipe.md +162 -0
  217. package/docs/ja/specdojo/recipes/ifd-recipe.md +145 -0
  218. package/docs/ja/specdojo/recipes/ifx-cmd-recipe.md +112 -90
  219. package/docs/ja/specdojo/recipes/ifx-index-recipe.md +164 -0
  220. package/docs/ja/specdojo/recipes/pm-communication-plan-recipe.md +60 -49
  221. package/docs/ja/specdojo/recipes/pm-members-recipe.md +50 -51
  222. package/docs/ja/specdojo/recipes/pm-organization-recipe.md +59 -48
  223. package/docs/ja/specdojo/recipes/pm-plan-recipe.md +72 -50
  224. package/docs/ja/specdojo/recipes/pm-quality-management-plan-recipe.md +40 -49
  225. package/docs/ja/specdojo/recipes/pm-raci-recipe.md +42 -48
  226. package/docs/ja/specdojo/recipes/pm-roles-recipe.md +52 -81
  227. package/docs/ja/specdojo/recipes/prj-assumptions-constraints-dependencies-recipe.md +64 -91
  228. package/docs/ja/specdojo/recipes/prj-charter-recipe.md +71 -106
  229. package/docs/ja/specdojo/recipes/prj-comparison-of-alternatives-recipe.md +78 -156
  230. package/docs/ja/specdojo/recipes/prj-issues-and-approach-recipe.md +62 -111
  231. package/docs/ja/specdojo/recipes/prj-scope-recipe.md +67 -123
  232. package/docs/ja/specdojo/recipes/prj-stakeholder-register-recipe.md +60 -96
  233. package/docs/ja/specdojo/recipes/prj-success-criteria-and-acceptance-criteria-recipe.md +61 -105
  234. package/docs/ja/specdojo/recipes/stsd-recipe.md +88 -80
  235. package/docs/ja/specdojo/recipes/sysd-critical-flows-recipe.md +129 -0
  236. package/docs/ja/specdojo/recipes/sysd-cross-cutting-policy-recipe.md +146 -0
  237. package/docs/ja/specdojo/recipes/sysd-index-recipe.md +141 -0
  238. package/docs/ja/specdojo/recipes/tsd-recipe.md +149 -129
  239. package/docs/ja/specdojo/references/command-reference.md +303 -148
  240. package/docs/ja/specdojo/references/deliverables-reference.md +30 -16
  241. package/docs/ja/specdojo/references/directory-layout-reference.md +3 -2
  242. package/docs/ja/specdojo/references/specdojo-config-reference.md +54 -18
  243. package/docs/ja/specdojo/rulebooks/atc-index-rulebook.md +101 -257
  244. package/docs/ja/specdojo/rulebooks/atc-rulebook.md +102 -228
  245. package/docs/ja/specdojo/rulebooks/bac-rulebook.md +63 -290
  246. package/docs/ja/specdojo/rulebooks/bdd-rulebook.md +162 -80
  247. package/docs/ja/specdojo/rulebooks/bds-rulebook.md +118 -155
  248. package/docs/ja/specdojo/rulebooks/bes-index-rulebook.md +128 -60
  249. package/docs/ja/specdojo/rulebooks/bes-rulebook.md +70 -94
  250. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +24 -56
  251. package/docs/ja/specdojo/rulebooks/br-rulebook.md +58 -103
  252. package/docs/ja/specdojo/rulebooks/ccd-mermaid-rulebook.md +103 -223
  253. package/docs/ja/specdojo/rulebooks/cdfd-d2-rulebook.md +18 -93
  254. package/docs/ja/specdojo/rulebooks/cdfd-mermaid-rulebook.md +18 -52
  255. package/docs/ja/specdojo/rulebooks/cdfd-overview-rulebook.md +109 -147
  256. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +80 -108
  257. package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +51 -55
  258. package/docs/ja/specdojo/rulebooks/cdr-rulebook.md +144 -0
  259. package/docs/ja/specdojo/rulebooks/cdsd-rulebook.md +81 -68
  260. package/docs/ja/specdojo/rulebooks/cdt-rulebook.md +139 -0
  261. package/docs/ja/specdojo/rulebooks/cld-rulebook.md +9 -184
  262. package/docs/ja/specdojo/rulebooks/clis-rulebook.md +170 -0
  263. package/docs/ja/specdojo/rulebooks/cnd-mermaid-rulebook.md +33 -86
  264. package/docs/ja/specdojo/rulebooks/cnd-rulebook.md +79 -249
  265. package/docs/ja/specdojo/rulebooks/cop-index-rulebook.md +45 -131
  266. package/docs/ja/specdojo/rulebooks/cop-rulebook.md +69 -275
  267. package/docs/ja/specdojo/rulebooks/cpd-mermaid-rulebook.md +20 -112
  268. package/docs/ja/specdojo/rulebooks/cpd-rulebook.md +79 -249
  269. package/docs/ja/specdojo/rulebooks/cxd-mermaid-rulebook.md +12 -145
  270. package/docs/ja/specdojo/rulebooks/cxd-rulebook.md +115 -256
  271. package/docs/ja/specdojo/rulebooks/dct-index-rulebook.md +79 -109
  272. package/docs/ja/specdojo/rulebooks/dct-rulebook.md +119 -174
  273. package/docs/ja/specdojo/rulebooks/dec-rulebook.md +6 -14
  274. package/docs/ja/specdojo/rulebooks/dmd-index-rulebook.md +22 -66
  275. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +36 -94
  276. package/docs/ja/specdojo/rulebooks/dss-rulebook.md +171 -0
  277. package/docs/ja/specdojo/rulebooks/etc-index-rulebook.md +31 -131
  278. package/docs/ja/specdojo/rulebooks/etc-rulebook.md +50 -104
  279. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +93 -57
  280. package/docs/ja/specdojo/rulebooks/ifd-mermaid-rulebook.md +63 -253
  281. package/docs/ja/specdojo/rulebooks/ifx-api-rulebook.md +14 -20
  282. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +79 -76
  283. package/docs/ja/specdojo/rulebooks/ifx-file-rulebook.md +182 -237
  284. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +111 -40
  285. package/docs/ja/specdojo/rulebooks/ifx-msg-rulebook.md +14 -22
  286. package/docs/ja/specdojo/rulebooks/imp-business-rulebook.md +23 -46
  287. package/docs/ja/specdojo/rulebooks/imp-data-rulebook.md +41 -64
  288. package/docs/ja/specdojo/rulebooks/imp-interface-rulebook.md +16 -40
  289. package/docs/ja/specdojo/rulebooks/imp-operations-rulebook.md +34 -61
  290. package/docs/ja/specdojo/rulebooks/imp-test-rulebook.md +27 -50
  291. package/docs/ja/specdojo/rulebooks/itc-index-rulebook.md +70 -199
  292. package/docs/ja/specdojo/rulebooks/itc-rulebook.md +65 -153
  293. package/docs/ja/specdojo/rulebooks/mip-index-rulebook.md +74 -150
  294. package/docs/ja/specdojo/rulebooks/mm-rulebook.md +12 -23
  295. package/docs/ja/specdojo/rulebooks/mtp-rulebook.md +99 -176
  296. package/docs/ja/specdojo/rulebooks/nfr-availability-rulebook.md +35 -61
  297. package/docs/ja/specdojo/rulebooks/nfr-index-rulebook.md +75 -117
  298. package/docs/ja/specdojo/rulebooks/nfr-integrity-rulebook.md +31 -60
  299. package/docs/ja/specdojo/rulebooks/nfr-maintainability-rulebook.md +26 -81
  300. package/docs/ja/specdojo/rulebooks/nfr-operations-rulebook.md +32 -70
  301. package/docs/ja/specdojo/rulebooks/nfr-performance-rulebook.md +45 -87
  302. package/docs/ja/specdojo/rulebooks/nfr-reliability-rulebook.md +48 -101
  303. package/docs/ja/specdojo/rulebooks/nfr-security-safety-rulebook.md +44 -80
  304. package/docs/ja/specdojo/rulebooks/nfr-usability-rulebook.md +59 -127
  305. package/docs/ja/specdojo/rulebooks/opd-index-rulebook.md +31 -50
  306. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +42 -109
  307. package/docs/ja/specdojo/rulebooks/opr-index-rulebook.md +29 -42
  308. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +29 -87
  309. package/docs/ja/specdojo/rulebooks/otp-index-rulebook.md +62 -84
  310. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +11 -61
  311. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +92 -102
  312. package/docs/ja/specdojo/rulebooks/pm-change-request-log-rulebook.md +25 -34
  313. package/docs/ja/specdojo/rulebooks/pm-communication-plan-rulebook.md +30 -53
  314. package/docs/ja/specdojo/rulebooks/pm-issue-log-rulebook.md +23 -35
  315. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +27 -45
  316. package/docs/ja/specdojo/rulebooks/pm-organization-rulebook.md +45 -59
  317. package/docs/ja/specdojo/rulebooks/pm-plan-rulebook.md +56 -66
  318. package/docs/ja/specdojo/rulebooks/pm-quality-management-plan-rulebook.md +54 -62
  319. package/docs/ja/specdojo/rulebooks/pm-raci-rulebook.md +46 -65
  320. package/docs/ja/specdojo/rulebooks/pm-risk-register-rulebook.md +28 -35
  321. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +65 -97
  322. package/docs/ja/specdojo/rulebooks/pr-rulebook.md +6 -18
  323. package/docs/ja/specdojo/rulebooks/prj-assumptions-constraints-dependencies-rulebook.md +48 -78
  324. package/docs/ja/specdojo/rulebooks/prj-charter-rulebook.md +23 -97
  325. package/docs/ja/specdojo/rulebooks/prj-comparison-of-alternatives-rulebook.md +61 -153
  326. package/docs/ja/specdojo/rulebooks/prj-issues-and-approach-rulebook.md +43 -116
  327. package/docs/ja/specdojo/rulebooks/prj-scope-rulebook.md +16 -51
  328. package/docs/ja/specdojo/rulebooks/prj-stakeholder-register-rulebook.md +47 -92
  329. package/docs/ja/specdojo/rulebooks/prj-success-criteria-and-acceptance-criteria-rulebook.md +25 -84
  330. package/docs/ja/specdojo/rulebooks/sac-rulebook.md +44 -107
  331. package/docs/ja/specdojo/rulebooks/sf-index-rulebook.md +106 -32
  332. package/docs/ja/specdojo/rulebooks/sf-rulebook.md +111 -61
  333. package/docs/ja/specdojo/rulebooks/sld-rulebook.md +129 -59
  334. package/docs/ja/specdojo/rulebooks/stc-index-rulebook.md +90 -189
  335. package/docs/ja/specdojo/rulebooks/stc-rulebook.md +45 -105
  336. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +46 -40
  337. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +104 -68
  338. package/docs/ja/specdojo/rulebooks/sysd-critical-flows-rulebook.md +64 -330
  339. package/docs/ja/specdojo/rulebooks/sysd-cross-cutting-policy-rulebook.md +70 -263
  340. package/docs/ja/specdojo/rulebooks/sysd-index-rulebook.md +58 -200
  341. package/docs/ja/specdojo/rulebooks/sysd-rulebook.md +47 -60
  342. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +4 -9
  343. package/docs/ja/specdojo/rulebooks/trc-requirements-to-specs-rulebook.md +69 -71
  344. package/docs/ja/specdojo/rulebooks/trc-requirements-to-tests-rulebook.md +65 -72
  345. package/docs/ja/specdojo/rulebooks/tsd-index-rulebook.md +35 -46
  346. package/docs/ja/specdojo/rulebooks/tsd-rulebook.md +49 -66
  347. package/docs/ja/specdojo/rulebooks/tsp-index-rulebook.md +64 -139
  348. package/docs/ja/specdojo/rulebooks/uis-rulebook.md +91 -161
  349. package/docs/ja/specdojo/rulebooks/utc-index-rulebook.md +49 -144
  350. package/docs/ja/specdojo/rulebooks/utc-rulebook.md +67 -155
  351. package/docs/ja/specdojo/samples/bac-sample.md +106 -21
  352. package/docs/ja/specdojo/samples/bdd-sample.yaml +143 -35
  353. package/docs/ja/specdojo/samples/bds-sample.md +87 -21
  354. package/docs/ja/specdojo/samples/bes-index-sample.md +42 -20
  355. package/docs/ja/specdojo/samples/bes-sample.md +70 -21
  356. package/docs/ja/specdojo/samples/bps-sample.md +42 -54
  357. package/docs/ja/specdojo/samples/br-sample.md +57 -15
  358. package/docs/ja/specdojo/samples/ccd-sample.md +80 -19
  359. package/docs/ja/specdojo/samples/cdfd-sample.md +172 -99
  360. package/docs/ja/specdojo/samples/cdfd-uc-sample.md +9 -7
  361. package/docs/ja/specdojo/samples/cdr-sample.md +78 -0
  362. package/docs/ja/specdojo/samples/cdsd-sample.md +73 -20
  363. package/docs/ja/specdojo/samples/cdt-sample.md +116 -0
  364. package/docs/ja/specdojo/samples/cld-sample.md +3 -30
  365. package/docs/ja/specdojo/samples/clis-sample.md +125 -0
  366. package/docs/ja/specdojo/samples/cnd-sample.md +127 -21
  367. package/docs/ja/specdojo/samples/cpd-sample.md +136 -22
  368. package/docs/ja/specdojo/samples/cxd-sample.md +108 -22
  369. package/docs/ja/specdojo/samples/dct-index-sample.yaml +63 -17
  370. package/docs/ja/specdojo/samples/dec-sample.md +2 -3
  371. package/docs/ja/specdojo/samples/dss-sample.md +175 -0
  372. package/docs/ja/specdojo/samples/gl-sample.yaml +50 -14
  373. package/docs/ja/specdojo/samples/ifd-sample.md +105 -21
  374. package/docs/ja/specdojo/samples/ifx-api-sample.yaml +0 -2
  375. package/docs/ja/specdojo/samples/ifx-cmd-sample.yaml +91 -60
  376. package/docs/ja/specdojo/samples/ifx-file-sample.md +462 -21
  377. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +87 -19
  378. package/docs/ja/specdojo/samples/ifx-msg-sample.yaml +0 -2
  379. package/docs/ja/specdojo/samples/job-sequence.yaml +67 -0
  380. package/docs/ja/specdojo/samples/mip-index-sample.md +98 -20
  381. package/docs/ja/specdojo/samples/pm-communication-plan-sample.md +26 -19
  382. package/docs/ja/specdojo/samples/pm-members-sample.yaml +37 -13
  383. package/docs/ja/specdojo/samples/pm-organization-sample.md +42 -21
  384. package/docs/ja/specdojo/samples/pm-plan-sample.md +78 -26
  385. package/docs/ja/specdojo/samples/pm-quality-management-plan-sample.md +41 -22
  386. package/docs/ja/specdojo/samples/pm-raci-sample.md +63 -28
  387. package/docs/ja/specdojo/samples/pm-roles-sample.yaml +13 -12
  388. package/docs/ja/specdojo/samples/prj-assumptions-constraints-dependencies-sample.md +33 -25
  389. package/docs/ja/specdojo/samples/prj-charter-sample.md +42 -59
  390. package/docs/ja/specdojo/samples/prj-comparison-of-alternatives-sample.md +83 -62
  391. package/docs/ja/specdojo/samples/prj-success-criteria-and-acceptance-criteria-sample.md +30 -33
  392. package/docs/ja/specdojo/samples/sf-index-sample.md +47 -20
  393. package/docs/ja/specdojo/samples/sf-sample.md +109 -21
  394. package/docs/ja/specdojo/samples/sld-sample.md +88 -21
  395. package/docs/ja/specdojo/samples/stsd-sample.md +54 -26
  396. package/docs/ja/specdojo/samples/sysd-critical-flows-sample.md +166 -21
  397. package/docs/ja/specdojo/samples/sysd-cross-cutting-policy-sample.md +178 -21
  398. package/docs/ja/specdojo/samples/sysd-index-sample.md +82 -21
  399. package/docs/ja/specdojo/samples/tml-sample.yaml +4 -1
  400. package/docs/ja/specdojo/samples/uis-sample.md +141 -20
  401. package/docs/ja/specdojo/standards/document-metadata-standard.md +33 -4
  402. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +3 -1
  403. package/docs/ja/specdojo/standards/job-definition-standard.md +24 -9
  404. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +1 -0
  405. package/docs/ja/specdojo/templates/bac-template.md +76 -0
  406. package/docs/ja/specdojo/templates/bes-template.md +56 -0
  407. package/docs/ja/specdojo/templates/br-template.md +64 -0
  408. package/docs/ja/specdojo/templates/cdfd-template.md +81 -54
  409. package/docs/ja/specdojo/templates/cdfd-uc-template.md +9 -5
  410. package/docs/ja/specdojo/templates/cdr-template.md +58 -0
  411. package/docs/ja/specdojo/templates/cnd-template.md +137 -0
  412. package/docs/ja/specdojo/templates/cpd-template.md +129 -0
  413. package/docs/ja/specdojo/templates/cxd-template.md +105 -0
  414. package/docs/ja/specdojo/templates/dct-data-model-cdt-template.yaml +40 -0
  415. package/docs/ja/specdojo/templates/dct-data-model-cld-template.yaml +7 -14
  416. package/docs/ja/specdojo/templates/dct-index-template.md +9 -20
  417. package/docs/ja/specdojo/templates/dct-project-management-template.yaml +5 -1
  418. package/docs/ja/specdojo/templates/ifd-template.md +86 -0
  419. package/docs/ja/specdojo/templates/ifx-cmd-template.yaml +44 -28
  420. package/docs/ja/specdojo/templates/ifx-index-template.yaml +40 -0
  421. package/docs/ja/specdojo/templates/opr-template.md +2 -4
  422. package/docs/ja/specdojo/templates/pm-organization-template.md +9 -3
  423. package/docs/ja/specdojo/templates/pm-plan-template.md +4 -4
  424. package/docs/ja/specdojo/templates/pm-quality-management-plan-template.md +17 -9
  425. package/docs/ja/specdojo/templates/pm-raci-template.md +24 -13
  426. package/docs/ja/specdojo/templates/pm-roles-template.yaml +3 -2
  427. package/docs/ja/specdojo/templates/prj-assumptions-constraints-dependencies-template.md +6 -3
  428. package/docs/ja/specdojo/templates/prj-comparison-of-alternatives-template.md +22 -19
  429. package/docs/ja/specdojo/templates/stsd-template.md +46 -21
  430. package/docs/ja/specdojo/templates/sysd-critical-flows-template.md +94 -0
  431. package/docs/ja/specdojo/templates/sysd-cross-cutting-policy-template.md +122 -0
  432. package/docs/ja/specdojo/templates/sysd-index-template.md +89 -0
  433. package/docs/specdojo/lib/yaml-metadata.cjs +7 -0
  434. package/docs/specdojo/schemas/v1/bdd.schema.yaml +25 -57
  435. package/docs/specdojo/schemas/v1/condense-records.schema.yaml +26 -0
  436. package/docs/specdojo/schemas/v1/dct.schema.yaml +10 -0
  437. package/docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml +3 -0
  438. package/docs/specdojo/schemas/v1/esil.schema.yaml +7 -141
  439. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +5 -1
  440. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +95 -8
  441. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +38 -0
  442. package/docs/specdojo/schemas/v1/exec-plan-frontmatter.schema.yaml +14 -0
  443. package/docs/specdojo/schemas/v1/exec-result-frontmatter.schema.yaml +18 -0
  444. package/docs/specdojo/schemas/v1/finding-cause.schema.yaml +22 -0
  445. package/docs/specdojo/schemas/v1/grade-pipeline-state.schema.yaml +1 -1
  446. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +2 -0
  447. package/docs/specdojo/schemas/v1/ifx-cmd.schema.yaml +65 -5
  448. package/docs/specdojo/schemas/v1/ifx-index.schema.yaml +142 -0
  449. package/docs/specdojo/schemas/v1/job-run.schema.yaml +23 -0
  450. package/docs/specdojo/schemas/v1/job.schema.yaml +63 -2
  451. package/docs/specdojo/schemas/v1/register-events.schema.yaml +2 -0
  452. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +17 -1
  453. package/docs/specdojo/schemas/v1/sch-strategy.schema.yaml +2 -2
  454. package/package.json +10 -7
  455. package/templates/antigravity/orchestrator.md +7 -3
  456. package/templates/claude/agents/specdojo-orchestrator.md +7 -3
  457. package/templates/codex/agents/specdojo-orchestrator.toml +7 -3
  458. package/templates/codex/orchestrator.md +7 -3
  459. package/templates/devcontainer/tmux.conf +6 -0
  460. package/templates/init-exec-defaults.yaml +13 -0
  461. package/templates/lefthook/tools/specdojo-pre-commit.mjs +8 -0
  462. package/templates/opencode/agents/specdojo-orchestrator.md +8 -4
@@ -2,8 +2,8 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
2
2
  import { dirname, relative, sep } from "node:path";
3
3
  import { dump } from "../shared/yaml.js";
4
4
  import { resolveSpecdojoPath } from "../docs/template-resolution.js";
5
- import { SEVERITIES, gradeContentHash, markdownDocumentId, resolveGradeResultsDirectory, gradeResultFileName, gradeResultPath, gradeResultPathForDocument, parseGradeResult, gradeFindingDisplayMessage, readGradeResult, readGradeResultForDocument, gradeFindingCount, } from "../shared/grade-result.js";
6
- export { SEVERITIES, gradeContentHash, markdownDocumentId, resolveGradeResultsDirectory, gradeResultFileName, gradeResultPath, gradeResultPathForDocument, parseGradeResult, gradeFindingDisplayMessage, readGradeResult, readGradeResultForDocument, gradeFindingCount, };
5
+ import { SEVERITIES, gradeContentHash, markdownDocumentId, gradeDocumentId, resolveGradeResultsDirectory, gradeResultFileName, gradeResultPath, gradeResultPathForDocument, parseGradeResult, gradeFindingDisplayMessage, readGradeResult, readGradeResultForDocument, gradeFindingCount, } from "../shared/grade-result.js";
6
+ export { SEVERITIES, gradeContentHash, markdownDocumentId, gradeDocumentId, resolveGradeResultsDirectory, gradeResultFileName, gradeResultPath, gradeResultPathForDocument, parseGradeResult, gradeFindingDisplayMessage, readGradeResult, readGradeResultForDocument, gradeFindingCount, };
7
7
  const GRADE_RESULT_SCHEMA = "docs/specdojo/schemas/v1/grade-result.schema.yaml";
8
8
  export function renderGradeResult(result, path) {
9
9
  const schemaRef = relative(dirname(path), resolveSpecdojoPath(GRADE_RESULT_SCHEMA))
@@ -149,7 +149,7 @@ export function validateGradeResult(result, documentContent, documentPath, expec
149
149
  const errors = [];
150
150
  let documentId;
151
151
  try {
152
- documentId = markdownDocumentId(documentContent, documentPath);
152
+ documentId = gradeDocumentId(documentContent, documentPath);
153
153
  }
154
154
  catch (error) {
155
155
  errors.push(error instanceof Error ? error.message : String(error));
package/dist/grade/run.js CHANGED
@@ -2,13 +2,44 @@ import { createHash } from "node:crypto";
2
2
  import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
3
3
  import { dirname, join, resolve } from "node:path";
4
4
  import { getProjectExecutionPath, specdojoRootDir } from "../shared/specdojo-config.js";
5
- import { tryAcquireLock, releaseLock } from "../shared/cross-process-lock.js";
5
+ import { delay, LOCK_POLL_MS, tryAcquireLock, releaseLock } from "../shared/cross-process-lock.js";
6
6
  import { applyGradeSubmission, buildGradeSubmissionFromAnalysis } from "./apply.js";
7
7
  import { readGradePipelineState, recordGradePipelineStage } from "./pipeline-state.js";
8
8
  import { writeGradePlans } from "./plan.js";
9
- import { gradeContentHash, readGradeResultForDocument } from "./result.js";
9
+ import { gradeContentHash, gradeFindingCount, readGradeResultForDocument } from "./result.js";
10
10
  import { discoverGradeTargets } from "./target-discovery.js";
11
11
  import { loadViewpoints, repoRelativePath, resolveDeliverableDoneCriteria, resolveGradeSourceHashes, resolveProject, resolveSafeMarkdownPath, resolveSafeRepositoryPath, } from "./targets.js";
12
+ /**
13
+ * A run that stopped with documents left ungraded. Callers such as scheduled jobs tell a
14
+ * partial run (2) from a run without any completed document (1) and from a rate limit (75),
15
+ * after which the same run id resumes.
16
+ */
17
+ export class GradeRunIncompleteError extends Error {
18
+ exitCode;
19
+ constructor(message, exitCode) {
20
+ super(message);
21
+ this.exitCode = exitCode;
22
+ this.name = "GradeRunIncompleteError";
23
+ }
24
+ }
25
+ export const GRADE_RUN_PARTIAL_EXIT_CODE = 2;
26
+ export const GRADE_RUN_RATE_LIMIT_EXIT_CODE = 75;
27
+ const PER_KIND_REFERENCES = {
28
+ rulebooks: "docs/ja/specdojo/rulebooks/prj-overview-rulebook.md",
29
+ recipes: "docs/ja/specdojo/recipes/prj-overview-recipe.md",
30
+ samples: "docs/ja/specdojo/samples/prj-overview-sample.md",
31
+ templates: "docs/ja/specdojo/templates/prj-overview-template.md",
32
+ };
33
+ function perKindReference(documentPath) {
34
+ const kindDirectory = documentPath.split("/").find((part) => part in PER_KIND_REFERENCES);
35
+ if (!kindDirectory)
36
+ throw new Error(`${documentPath}: cannot determine the Kata kind`);
37
+ const reference = PER_KIND_REFERENCES[kindDirectory];
38
+ if (existsSync(resolve(specdojoRootDir(), reference)))
39
+ return reference;
40
+ process.stderr.write(`grade run: ${documentPath}: same-kind reference not found; continuing without a reference: ${reference}\n`);
41
+ return undefined;
42
+ }
12
43
  const digest = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
13
44
  function referenceHash(reference, project) {
14
45
  return reference
@@ -23,13 +54,23 @@ function writeState(path, state) {
23
54
  }
24
55
  /** Native single-document pipeline. A stable run id freezes selection and completed work. */
25
56
  export async function runGrade(opts, runtime) {
57
+ if (opts.ifBusy !== undefined && opts.ifBusy !== "fail" && opts.ifBusy !== "wait")
58
+ throw new Error("Invalid --if-busy; expected fail or wait");
26
59
  // Serialize all runs for a project: different run ids still write the same canonical sidecars.
27
60
  if (opts.dryRun)
28
61
  return runGradeUnlocked(opts, runtime);
29
62
  const { project } = resolveProject(opts.project);
30
63
  const lockPath = resolveSafeRepositoryPath(join(getProjectExecutionPath(project), "grade", "generated", "run.lock"), "grade lock");
31
64
  mkdirSync(dirname(lockPath), { recursive: true });
32
- const lock = tryAcquireLock(lockPath, { actor: opts.by ?? "grade", label: opts.runId });
65
+ const owner = { actor: opts.by ?? "grade", label: opts.runId };
66
+ let lock = tryAcquireLock(lockPath, owner);
67
+ if (!lock && opts.ifBusy === "wait") {
68
+ process.stdout.write("grade run is busy for this project; waiting for the active run\n");
69
+ while (!lock) {
70
+ await delay(LOCK_POLL_MS);
71
+ lock = tryAcquireLock(lockPath, owner);
72
+ }
73
+ }
33
74
  if (!lock)
34
75
  throw new Error("grade run is busy for this project; retry after the active run finishes");
35
76
  try {
@@ -52,6 +93,10 @@ async function runGradeUnlocked(opts, runtime) {
52
93
  throw new Error("Invalid --max-stage-failures");
53
94
  if (opts.limit !== undefined && (!Number.isSafeInteger(opts.limit) || opts.limit < 1))
54
95
  throw new Error("Invalid --limit");
96
+ if (opts.referencePerKind && opts.target !== "kata")
97
+ throw new Error("--reference-per-kind is only valid for kata");
98
+ if (opts.referencePerKind && opts.reference !== undefined)
99
+ throw new Error("Use either --reference or --reference-per-kind");
55
100
  const { id: projectId, project } = resolveProject(opts.project);
56
101
  const viewpoints = loadViewpoints(projectId);
57
102
  const executionPath = getProjectExecutionPath(project);
@@ -61,7 +106,12 @@ async function runGradeUnlocked(opts, runtime) {
61
106
  : undefined);
62
107
  const directory = resolveSafeRepositoryPath(opts.workDir ?? join(executionPath, "grade", "generated", "runs", opts.runId), "--work-dir");
63
108
  const statePath = join(directory, "run.json");
64
- const requestOptions = Object.fromEntries(Object.entries(opts).filter(([key]) => key !== "dryRun"));
109
+ // Review preparation runs in the integration worktree. Its failures must never mutate
110
+ // shared retry state that another task may already have included in its checkpoint.
111
+ const pipelineStateDirectory = opts.isolatePipelineState
112
+ ? join(directory, "pipeline")
113
+ : undefined;
114
+ const requestOptions = Object.fromEntries(Object.entries(opts).filter(([key]) => key !== "dryRun" && key !== "ifBusy"));
65
115
  const request = digest({ ...requestOptions, project: projectId });
66
116
  let state;
67
117
  if (existsSync(statePath)) {
@@ -104,12 +154,16 @@ async function runGradeUnlocked(opts, runtime) {
104
154
  const criteria = opts.target === "deliverable"
105
155
  ? resolveDeliverableDoneCriteria(state.documents.map((document) => document.path), projectId)
106
156
  : undefined;
157
+ const references = new Map(state.documents.map((document) => [
158
+ document.path,
159
+ opts.referencePerKind ? perKindReference(document.path) : opts.reference,
160
+ ]));
107
161
  // Validate all subjects before starting any agent or writing run files.
108
162
  for (const document of state.documents) {
109
163
  const path = resolveSafeMarkdownPath(document.path, specdojoRootDir(), projectId);
110
164
  const fingerprint = digest({
111
165
  content: gradeContentHash(readFileSync(path, "utf8")),
112
- reference: referenceHash(opts.reference, projectId),
166
+ reference: referenceHash(references.get(document.path), projectId),
113
167
  viewpoints,
114
168
  criteria: criteria?.get(document.path),
115
169
  sources: resolveGradeSourceHashes({
@@ -158,8 +212,10 @@ async function runGradeUnlocked(opts, runtime) {
158
212
  writeState(statePath, state);
159
213
  const failures = [];
160
214
  for (const [index, document] of state.documents.entries()) {
215
+ const reference = references.get(document.path);
161
216
  if (document.status === "complete") {
162
217
  recordGradePipelineStage({
218
+ directory: pipelineStateDirectory,
163
219
  target: opts.target,
164
220
  project: projectId,
165
221
  path: document.path,
@@ -173,6 +229,7 @@ async function runGradeUnlocked(opts, runtime) {
173
229
  continue;
174
230
  }
175
231
  const prior = readGradePipelineState({
232
+ directory: pipelineStateDirectory,
176
233
  target: opts.target,
177
234
  project: projectId,
178
235
  path: document.path,
@@ -184,6 +241,7 @@ async function runGradeUnlocked(opts, runtime) {
184
241
  // The native runner has one stage. Old experimental three-stage retries cannot be reused.
185
242
  if (prior && prior.stage_total !== 1)
186
243
  recordGradePipelineStage({
244
+ directory: pipelineStateDirectory,
187
245
  target: opts.target,
188
246
  project: projectId,
189
247
  path: document.path,
@@ -199,7 +257,7 @@ async function runGradeUnlocked(opts, runtime) {
199
257
  target: opts.target,
200
258
  paths: [document.path],
201
259
  referenceExampleCandidates: [],
202
- referenceExampleOverride: opts.reference,
260
+ referenceExampleOverride: reference,
203
261
  viewpoints,
204
262
  projectId,
205
263
  outputDirectory: stageDirectory,
@@ -220,6 +278,18 @@ async function runGradeUnlocked(opts, runtime) {
220
278
  document.actor = actualActor;
221
279
  if (!execution)
222
280
  throw new Error("Agent returned no execution result");
281
+ if (execution.result === "rate_limit") {
282
+ // A rate limit is not a document failure: keep the stage retryable in this run id.
283
+ document.status = "pending";
284
+ writeState(statePath, state);
285
+ const unstarted = state.documents
286
+ .filter((item) => item.status !== "complete")
287
+ .map((item) => item.path);
288
+ throw new GradeRunIncompleteError([
289
+ `grade run stopped by rate limit: agent=${actualActor} run_id=${opts.runId}; rerun with the same --run-id to resume`,
290
+ ...unstarted.map((path) => `grade run remaining: ${path}`),
291
+ ].join("\n"), GRADE_RUN_RATE_LIMIT_EXIT_CODE);
292
+ }
223
293
  writeFileSync(join(stageDirectory, "executor-output.txt"), execution.stdout, "utf8");
224
294
  if (execution.result !== "success")
225
295
  throw new Error(`agent ${actualActor}: ${execution.result} exit=${execution.exitCode ?? "null"}`);
@@ -227,7 +297,7 @@ async function runGradeUnlocked(opts, runtime) {
227
297
  const currentPath = resolveSafeMarkdownPath(document.path, specdojoRootDir(), projectId);
228
298
  const currentFingerprint = digest({
229
299
  content: gradeContentHash(readFileSync(currentPath, "utf8")),
230
- reference: referenceHash(opts.reference, projectId),
300
+ reference: referenceHash(reference, projectId),
231
301
  viewpoints: loadViewpoints(projectId),
232
302
  criteria: opts.target === "deliverable"
233
303
  ? resolveDeliverableDoneCriteria([document.path], projectId).get(document.path)
@@ -256,7 +326,7 @@ async function runGradeUnlocked(opts, runtime) {
256
326
  viewpoints,
257
327
  target: opts.target,
258
328
  gradedBy: actualActor,
259
- reference: opts.reference,
329
+ reference,
260
330
  doneCriteriaByPath: criteria,
261
331
  criteriaDirectory: join(executionPath, "grade", "criteria"),
262
332
  resultsDirectory: join(executionPath, "grade", "results"),
@@ -273,6 +343,7 @@ async function runGradeUnlocked(opts, runtime) {
273
343
  document.resultHash = digest(result);
274
344
  writeState(statePath, state);
275
345
  recordGradePipelineStage({
346
+ directory: pipelineStateDirectory,
276
347
  target: opts.target,
277
348
  project: projectId,
278
349
  path: document.path,
@@ -282,13 +353,16 @@ async function runGradeUnlocked(opts, runtime) {
282
353
  maxFailures,
283
354
  status: "complete",
284
355
  });
285
- process.stdout.write(`graded: ${document.path} actor=${actualActor}\n`);
356
+ process.stdout.write(`graded: ${document.path} actor=${actualActor} verdict=${result.verdict} score=${result.score} findings=${gradeFindingCount(result)}\n`);
286
357
  }
287
358
  catch (error) {
359
+ if (error instanceof GradeRunIncompleteError)
360
+ throw error;
288
361
  document.status = "failed";
289
362
  document.error = error instanceof Error ? error.message : String(error);
290
363
  writeState(statePath, state);
291
364
  recordGradePipelineStage({
365
+ directory: pipelineStateDirectory,
292
366
  target: opts.target,
293
367
  project: projectId,
294
368
  path: document.path,
@@ -301,7 +375,9 @@ async function runGradeUnlocked(opts, runtime) {
301
375
  failures.push(`${document.path}: ${document.error}`);
302
376
  }
303
377
  }
304
- if (failures.length)
305
- throw new Error(`grade run incomplete:\n${failures.join("\n")}`);
378
+ if (failures.length) {
379
+ const completed = state.documents.filter((document) => document.status === "complete").length;
380
+ throw new GradeRunIncompleteError(`grade run incomplete: completed=${completed} failed=${failures.length} run_id=${opts.runId}\n${failures.join("\n")}`, completed > 0 ? GRADE_RUN_PARTIAL_EXIT_CODE : 1);
381
+ }
306
382
  return { documents: state.documents };
307
383
  }
@@ -1,9 +1,10 @@
1
+ import { isGradeDocument, isYamlDocument } from "../shared/document-metadata.js";
1
2
  import { existsSync, readFileSync } from "node:fs";
2
3
  import { join } from "node:path";
3
4
  import { buildScheduleIndex } from "../shared/schedule-index.js";
4
5
  import { listFilesRecursive } from "../shared/fs.js";
5
6
  import { gradeContentHash, gradeFindingCount, readGradeResultForDocument } from "./result.js";
6
- import { KATA_DIRS, isRecord, legacyInlineContentHash, parseMarkdown, } from "./core.js";
7
+ import { KATA_DIRS, isRecord, legacyInlineContentHash, parseGradeDocument, } from "./core.js";
7
8
  import { currentGradePipelineState, isIncompleteGradePipelineState, loadGradePipelineStates, } from "./pipeline-state.js";
8
9
  import { comparisonSourceKeys, createGradeSourceContext, currentSourceHashes, dependencySourceKeys, gradedComparisonSources, isGeneratedGradeTarget, isTrashedGradeTarget, loadDeliverableCatalog, loadViewpointsIfConfigured, relativePathFromRoot, resolveProject, resolveSafeMarkdownPath, sourceHashesChanged, } from "./targets.js";
9
10
  import { getProjectExecutionPath, specdojoRootDir } from "../shared/specdojo-config.js";
@@ -23,7 +24,7 @@ export function discoverGradeTargets(opts, rootDir = specdojoRootDir()) {
23
24
  }
24
25
  else if (opts.target === "kata") {
25
26
  // 対象の列挙は利用リポジトリ限定。eject されていない kata は評価対象にしない。
26
- candidates = KATA_DIRS.flatMap((dir) => listFilesRecursive(join(rootDir, "docs/ja/specdojo", dir)).filter((entry) => entry.endsWith(".md")));
27
+ candidates = KATA_DIRS.flatMap((dir) => listFilesRecursive(join(rootDir, "docs/ja/specdojo", dir)).filter((entry) => isGradeDocument(entry)));
27
28
  }
28
29
  else {
29
30
  candidates = [...loadDeliverableCatalog(opts.project, rootDir).keys()];
@@ -31,6 +32,18 @@ export function discoverGradeTargets(opts, rootDir = specdojoRootDir()) {
31
32
  const unique = [...new Set(candidates)]
32
33
  .filter((path) => !isGeneratedGradeTarget(path, rootDir))
33
34
  .filter((path) => !isTrashedGradeTarget(path, rootDir))
35
+ .filter((path) => {
36
+ if (!isYamlDocument(path))
37
+ return true;
38
+ try {
39
+ parseGradeDocument(readFileSync(path, "utf8"), relativePathFromRoot(path, rootDir));
40
+ return true;
41
+ }
42
+ catch (error) {
43
+ console.warn(`grade: skipped ${error instanceof Error ? error.message : String(error)}`);
44
+ return false;
45
+ }
46
+ })
34
47
  .sort();
35
48
  if (!opts.changedOnly &&
36
49
  !opts.dependencyChanged &&
@@ -94,7 +107,7 @@ export function discoverGradeTargets(opts, rootDir = specdojoRootDir()) {
94
107
  return unique.filter((path) => {
95
108
  const rel = relativePathFromRoot(path, rootDir);
96
109
  const content = readFileSync(path, "utf8");
97
- const document = parseMarkdown(content, rel);
110
+ const document = parseGradeDocument(content, rel);
98
111
  const pipelineState = currentGradePipelineState(document, rel, pipelineStates.get(rel), opts.target);
99
112
  const result = readGradeResultForDocument({
100
113
  documentPath: rel,
@@ -258,7 +271,7 @@ function matchesParsedGradeTargetFilters(document, path, filters, incomplete = f
258
271
  }
259
272
  export function matchesGradeTargetFilters(content, path, filters, pipelineState) {
260
273
  validateGradeTargetFilters(filters);
261
- const document = parseMarkdown(content, path);
274
+ const document = parseGradeDocument(content, path);
262
275
  const currentState = currentGradePipelineState(document, path, pipelineState);
263
276
  return matchesParsedGradeTargetFilters(document, path, filters, isIncompleteGradePipelineState(currentState));
264
277
  }
@@ -1,3 +1,4 @@
1
+ import { isGradeDocument, isYamlDocument } from "../shared/document-metadata.js";
1
2
  import { createHash } from "node:crypto";
2
3
  import { existsSync, readFileSync, realpathSync } from "node:fs";
3
4
  import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
@@ -6,7 +7,7 @@ import { collectResolvedDeliverables, loadCatalogDocs } from "../catalog/build.j
6
7
  import { isTrashedPath, resolveBasePath } from "../catalog/paths.js";
7
8
  import { listFilesRecursive } from "../shared/fs.js";
8
9
  import { gradeContentHash } from "./result.js";
9
- import { GRADE_TARGETS, KATA_DIRS, KATA_REFERENCE_EXTENSIONS, KATA_REFERENCE_FIELDS, gradedViewpoints, isRecord, parseMarkdown, } from "./core.js";
10
+ import { GRADE_TARGETS, KATA_DIRS, KATA_REFERENCE_EXTENSIONS, KATA_REFERENCE_FIELDS, gradedViewpoints, isRecord, parseGradeDocument, } from "./core.js";
10
11
  import { commonViewpointsPath, resolveViewpointsDoc } from "../review/plan.js";
11
12
  import { assertValidActor, getProjectCatalogPath, getProjectMembersPath, getProjectRolesPath, getProjectSchedulePath, getProjectViewpointsPath, loadConfig, resolveAgentMember, resolveRepoRoot, specdojoRootDir, } from "../shared/specdojo-config.js";
12
13
  export function resolveProject(projectOption) {
@@ -83,8 +84,8 @@ function parseKataReference(path, kind) {
83
84
  try {
84
85
  const extension = extname(path).toLowerCase();
85
86
  let metadata;
86
- if (extension === ".md") {
87
- metadata = parseMarkdown(readFileSync(path, "utf8"), repoRelativePath(path)).data
87
+ if (extension === ".md" || isYamlDocument(path)) {
88
+ metadata = parseGradeDocument(readFileSync(path, "utf8"), repoRelativePath(path)).data
88
89
  .specdojo;
89
90
  }
90
91
  else {
@@ -125,7 +126,7 @@ export function loadKataReferences() {
125
126
  }
126
127
  export function resolveGradeReferencePathsFromCatalog(path, catalog, project) {
127
128
  const target = resolveSafeMarkdownPath(path, specdojoRootDir(), project);
128
- const targetDocument = parseMarkdown(readFileSync(target, "utf8"), repoRelativePath(target));
129
+ const targetDocument = parseGradeDocument(readFileSync(target, "utf8"), repoRelativePath(target));
129
130
  const targetMetadata = targetDocument.data.specdojo;
130
131
  const targetId = typeof targetMetadata.id === "string" ? targetMetadata.id.trim() : "";
131
132
  if (!targetId)
@@ -172,7 +173,7 @@ function gradeReferenceExampleFamily(target, path, metadata) {
172
173
  export function parseGradeReferenceExample(path, target, project) {
173
174
  try {
174
175
  const absolute = resolveSafeMarkdownPath(path, specdojoRootDir(), project);
175
- const document = parseMarkdown(readFileSync(absolute, "utf8"), repoRelativePath(absolute));
176
+ const document = parseGradeDocument(readFileSync(absolute, "utf8"), repoRelativePath(absolute));
176
177
  const metadata = document.data.specdojo;
177
178
  return {
178
179
  path: absolute,
@@ -186,7 +187,7 @@ export function parseGradeReferenceExample(path, target, project) {
186
187
  }
187
188
  export function selectGradeReferenceExampleFromCatalog(opts) {
188
189
  const target = resolveSafeMarkdownPath(opts.path, specdojoRootDir(), opts.project);
189
- const targetDocument = parseMarkdown(readFileSync(target, "utf8"), repoRelativePath(target));
190
+ const targetDocument = parseGradeDocument(readFileSync(target, "utf8"), repoRelativePath(target));
190
191
  const targetMetadata = targetDocument.data.specdojo;
191
192
  const family = gradeReferenceExampleFamily(opts.target, target, targetMetadata);
192
193
  if (!family)
@@ -233,8 +234,8 @@ export function resolveSafeMarkdownPath(input, root = specdojoRootDir(), project
233
234
  }
234
235
  if (!roots.some((base) => inside(base, absolute)))
235
236
  throw new Error(`Path is outside repository or declared project.repos: ${input}`);
236
- if (extname(absolute).toLowerCase() !== ".md") {
237
- throw new Error(`${input}: grade currently writes inline findings only for Markdown`);
237
+ if (!isGradeDocument(absolute)) {
238
+ throw new Error(`${input}: grade supports Markdown and YAML documents`);
238
239
  }
239
240
  if (!existsSync(absolute))
240
241
  throw new Error(`Document not found: ${input}`);
@@ -266,7 +267,7 @@ export function isTrashedGradeTarget(path, rootDir = specdojoRootDir()) {
266
267
  function criterionId(index) {
267
268
  return `DC-${String(index + 1).padStart(3, "0")}`;
268
269
  }
269
- // カタログの Markdown 成果物を絶対パスで引ける形にする。grade の対象探索と
270
+ // カタログの評価可能な成果物を絶対パスで引ける形にする。grade の対象探索と
270
271
  // done_criteria の解決が同じ集合を見るよう、両者はこの関数を共有する。
271
272
  export function loadDeliverableCatalog(projectOption, root = specdojoRootDir()) {
272
273
  const { project } = resolveProject(projectOption);
@@ -280,7 +281,7 @@ export function loadDeliverableCatalog(projectOption, root = specdojoRootDir())
280
281
  for (const item of resolved) {
281
282
  if (item.item.kind === "generated" || !item.item.path)
282
283
  continue;
283
- if (!item.resolvedPath.endsWith(".md"))
284
+ if (!isGradeDocument(item.resolvedPath))
284
285
  continue;
285
286
  if (isTrashedPath(item.resolvedPath))
286
287
  continue;
@@ -447,7 +448,7 @@ export function gradeSourceHashes(documentPath, document, viewpoints, target, co
447
448
  /** Current hashes of the comparison sources and dependencies that grade apply records for a document. */
448
449
  export function resolveGradeSourceHashes(opts, rootDir = specdojoRootDir()) {
449
450
  const absolute = resolveSafeMarkdownPath(opts.path, rootDir, opts.project);
450
- const document = parseMarkdown(readFileSync(absolute, "utf8"), relativePathFromRoot(absolute, rootDir));
451
+ const document = parseGradeDocument(readFileSync(absolute, "utf8"), relativePathFromRoot(absolute, rootDir));
451
452
  const viewpoints = opts.viewpoints ?? loadViewpointsIfConfigured(opts.project, rootDir);
452
453
  return gradeSourceHashes(absolute, document, viewpoints, opts.target, createGradeSourceContext(opts.project, rootDir));
453
454
  }
@@ -3,6 +3,7 @@ import { basename, join, resolve } from "node:path";
3
3
  import { load } from "../shared/yaml.js";
4
4
  import { listFilesRecursive, readJson } from "../shared/fs.js";
5
5
  import { getProjectExecutionPath, getProjectJobsPath, loadConfig, loadEnv, specdojoRootDir, } from "../shared/specdojo-config.js";
6
+ import { isProficiency, PROFICIENCIES, } from "../shared/agent-types.js";
6
7
  function isRecord(value) {
7
8
  return typeof value === "object" && value !== null && !Array.isArray(value);
8
9
  }
@@ -17,6 +18,65 @@ function validStringList(value) {
17
18
  value.length > 0 &&
18
19
  value.every((item) => typeof item === "string" && item.trim()));
19
20
  }
21
+ export function parseJobSteps(value) {
22
+ const errors = [];
23
+ if (!Array.isArray(value) || value.length === 0)
24
+ return { errors: ["task.steps must be a non-empty list"] };
25
+ const steps = [];
26
+ const ids = new Set();
27
+ for (const [index, raw] of value.entries()) {
28
+ const prefix = `task.steps[${index}]`;
29
+ if (!isRecord(raw)) {
30
+ errors.push(`${prefix} must be a mapping`);
31
+ continue;
32
+ }
33
+ if (Object.keys(raw).some((key) => !["id", "command", "on_failure", "timeout_seconds", "completion"].includes(key)))
34
+ errors.push(`${prefix} has unknown keys`);
35
+ if (typeof raw.id !== "string" || !/^[a-z][a-z0-9-]*$/.test(raw.id) || ids.has(raw.id))
36
+ errors.push(`${prefix}.id must be a unique lowercase slug`);
37
+ else
38
+ ids.add(raw.id);
39
+ if (typeof raw.command !== "string" || !raw.command.trim())
40
+ errors.push(`${prefix}.command must be non-empty`);
41
+ if (raw.on_failure !== undefined && raw.on_failure !== "stop" && raw.on_failure !== "continue")
42
+ errors.push(`${prefix}.on_failure must be stop|continue`);
43
+ if (raw.timeout_seconds !== undefined &&
44
+ (!Number.isSafeInteger(raw.timeout_seconds) ||
45
+ Number(raw.timeout_seconds) < 1 ||
46
+ Number(raw.timeout_seconds) > 2147483))
47
+ errors.push(`${prefix}.timeout_seconds must be an integer from 1 to 2147483`);
48
+ let completion;
49
+ if (raw.completion !== undefined) {
50
+ const state = raw.completion;
51
+ if (!isRecord(state) ||
52
+ Object.keys(state).some((key) => !["path", "field", "succeeded", "deferred"].includes(key)) ||
53
+ typeof state.path !== "string" ||
54
+ !state.path.trim() ||
55
+ typeof state.field !== "string" ||
56
+ !state.field.trim() ||
57
+ !validStringList(state.succeeded) ||
58
+ (state.deferred !== undefined && !validStringList(state.deferred)) ||
59
+ (Array.isArray(state.deferred) &&
60
+ state.deferred.some((item) => state.succeeded.includes(item))))
61
+ errors.push(`${prefix}.completion requires path, field and disjoint succeeded/deferred state lists`);
62
+ else
63
+ completion = state;
64
+ }
65
+ steps.push({
66
+ id: String(raw.id),
67
+ command: String(raw.command),
68
+ ...(raw.on_failure ? { on_failure: raw.on_failure } : {}),
69
+ ...(raw.timeout_seconds !== undefined
70
+ ? { timeout_seconds: Number(raw.timeout_seconds) }
71
+ : {}),
72
+ ...(completion ? { completion } : {}),
73
+ });
74
+ }
75
+ return { ...(errors.length === 0 ? { steps } : {}), errors };
76
+ }
77
+ export function jobCommandText(task) {
78
+ return (task.steps?.map((step) => `# ${step.id}\n${step.command}`).join("\n") ?? task.command ?? "");
79
+ }
20
80
  // Same nickname shape as agent-members.schema.yaml. The roster is not loaded here, so a
21
81
  // definition only guarantees the format; an unknown nickname fails when the Run resolves
22
82
  // the agent command.
@@ -133,7 +193,8 @@ function isJobTaskDefinition(value) {
133
193
  if (value.review !== undefined && !isJobReviewDefinition(value.review))
134
194
  return false;
135
195
  if (value.mode === "command") {
136
- return (typeof value.command === "string" &&
196
+ return (((typeof value.command === "string" && value.steps === undefined) ||
197
+ (value.command === undefined && parseJobSteps(value.steps).errors.length === 0)) &&
137
198
  (value.partial_exit_code === undefined ||
138
199
  (Number.isSafeInteger(value.partial_exit_code) &&
139
200
  Number(value.partial_exit_code) >= 1 &&
@@ -377,8 +438,19 @@ export function parseJobDefinition(value, fileName) {
377
438
  };
378
439
  if (mode === "command") {
379
440
  const command = typeof value.task.command === "string" ? value.task.command.trim() : "";
380
- if (!command)
381
- errors.push("task.command is required for command mode");
441
+ const parsedSteps = value.task.steps === undefined ? undefined : parseJobSteps(value.task.steps);
442
+ if (parsedSteps)
443
+ errors.push(...parsedSteps.errors);
444
+ if ((value.task.command !== undefined) === (value.task.steps !== undefined) ||
445
+ (value.task.command !== undefined && !command))
446
+ errors.push("command mode requires exactly one of task.command or task.steps");
447
+ if (value.task.lock_wait_seconds !== undefined &&
448
+ (!parsedSteps ||
449
+ !Number.isSafeInteger(value.task.lock_wait_seconds) ||
450
+ Number(value.task.lock_wait_seconds) < 0))
451
+ errors.push("task.lock_wait_seconds must be a non-negative integer for task.steps");
452
+ if (parsedSteps && value.task.partial_exit_code !== undefined)
453
+ errors.push("task.partial_exit_code cannot be combined with task.steps");
382
454
  const partialExitCode = value.task.partial_exit_code;
383
455
  if (partialExitCode !== undefined &&
384
456
  (!Number.isSafeInteger(partialExitCode) ||
@@ -448,11 +520,14 @@ export function parseJobDefinition(value, fileName) {
448
520
  if (value.task.capabilities !== undefined || value.task.proficiency !== undefined) {
449
521
  errors.push("task.capabilities and task.proficiency are not allowed in command mode");
450
522
  }
451
- if (command)
523
+ if (command || parsedSteps?.steps)
452
524
  task = {
453
525
  mode: "command",
454
526
  ...(precondition ? { precondition } : {}),
455
- command,
527
+ ...(parsedSteps?.steps ? { steps: parsedSteps.steps } : { command }),
528
+ ...(value.task.lock_wait_seconds !== undefined
529
+ ? { lock_wait_seconds: Number(value.task.lock_wait_seconds) }
530
+ : {}),
456
531
  ...(Number.isSafeInteger(partialExitCode)
457
532
  ? { partial_exit_code: Number(partialExitCode) }
458
533
  : {}),
@@ -478,6 +553,8 @@ export function parseJobDefinition(value, fileName) {
478
553
  }
479
554
  if (value.task.analysis !== undefined ||
480
555
  value.task.command !== undefined ||
556
+ value.task.steps !== undefined ||
557
+ value.task.lock_wait_seconds !== undefined ||
481
558
  value.task.precondition !== undefined ||
482
559
  value.task.partial_exit_code !== undefined) {
483
560
  errors.push("task.command, task.precondition, task.partial_exit_code, and task.analysis are only allowed in command mode");
@@ -486,9 +563,8 @@ export function parseJobDefinition(value, fileName) {
486
563
  errors.push("task.capabilities must be a non-empty string list");
487
564
  }
488
565
  const proficiency = value.task.proficiency;
489
- if (proficiency !== undefined &&
490
- !["low", "normal", "high", "expert"].includes(String(proficiency))) {
491
- errors.push("task.proficiency must be low|normal|high|expert");
566
+ if (proficiency !== undefined && !isProficiency(proficiency)) {
567
+ errors.push(`task.proficiency must be ${PROFICIENCIES.join("|")}`);
492
568
  }
493
569
  if ((mode === "edit" || mode === "review") && description && (targets || paths)) {
494
570
  task = {