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
@@ -0,0 +1,25 @@
1
+ import { isFindingCause } from "./finding-cause.js";
2
+ export const CONDENSE_CATEGORIES = [
3
+ "repetition",
4
+ "table-prose",
5
+ "figure-prose",
6
+ "unneeded-background",
7
+ "canonical-restatement",
8
+ ];
9
+ export const CONDENSE_ACTIONS = ["delete", "merge", "reference", "retain"];
10
+ export function isCondenseRecords(value) {
11
+ return (Array.isArray(value) &&
12
+ value.length <= 100 &&
13
+ value.every((entry) => {
14
+ if (!entry || typeof entry !== "object" || Array.isArray(entry))
15
+ return false;
16
+ const record = entry;
17
+ const text = (value) => typeof value === "string" && value.trim().length > 0 && value.length <= 4000;
18
+ return (Object.keys(record).length === 5 &&
19
+ text(record.location) &&
20
+ text(record.reason) &&
21
+ CONDENSE_CATEGORIES.includes(record.category) &&
22
+ CONDENSE_ACTIONS.includes(record.action) &&
23
+ isFindingCause(record.cause));
24
+ }));
25
+ }
@@ -1,5 +1,6 @@
1
1
  import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, utimesSync, } from "node:fs";
2
2
  import { spawn } from "node:child_process";
3
+ import { AsyncLocalStorage } from "node:async_hooks";
3
4
  import { join } from "node:path";
4
5
  import { ensureDir, writeJson } from "./fs.js";
5
6
  import { randomHex } from "./random.js";
@@ -11,6 +12,13 @@ import { nowUtcIsoSeconds } from "./time.js";
11
12
  export const LOCK_HEARTBEAT_MS = 5_000;
12
13
  export const LOCK_STALE_MS = 30_000;
13
14
  export const LOCK_POLL_MS = 200;
15
+ // Propagate only locks held by this async operation to Git hooks, without changing process.env.
16
+ export const GIT_LOCK_TOKENS_ENV = "SPECDOJO_GIT_LOCK_TOKENS";
17
+ const heldLocks = new AsyncLocalStorage();
18
+ export function gitLockEnvironment() {
19
+ const locks = heldLocks.getStore();
20
+ return locks?.length ? { [GIT_LOCK_TOKENS_ENV]: locks.map((lock) => lock.token).join(",") } : {};
21
+ }
14
22
  // The lock directory of the project whose exec-run lock this process holds. Gates that are
15
23
  // reached through many call paths (parent validations) read it instead of having the directory
16
24
  // threaded through every caller. One `exec run` process serves one project.
@@ -231,7 +239,7 @@ export class CrossProcessMutex {
231
239
  try {
232
240
  const handle = await acquirePoolSlot(this.poolDir, 1, this.owner, this.options);
233
241
  try {
234
- return await fn();
242
+ return await heldLocks.run([...(heldLocks.getStore() ?? []), handle], fn);
235
243
  }
236
244
  finally {
237
245
  releaseLock(handle);
@@ -0,0 +1,8 @@
1
+ const warned = new Set();
2
+ /** Emit each compatibility warning once per CLI process, even across repeated loads. */
3
+ export function warnDeprecated(feature, migration) {
4
+ if (warned.has(feature))
5
+ return;
6
+ warned.add(feature);
7
+ process.stderr.write(`WARN: ${feature} is deprecated. ${migration}\n`);
8
+ }
@@ -4,6 +4,8 @@ import path from "node:path";
4
4
  const SKIP_ENV_NAME = "SPECDOJO_SKIP_DIST_FRESHNESS_CHECK";
5
5
  const SKIP_ENV_VALUES = new Set(["1", "true", "yes"]);
6
6
  const IGNORED_DIRECTORY_NAMES = new Set(["node_modules", ".git"]);
7
+ // A failed tsc may still emit newer JS. A successful clean build removes this marker with dist/.
8
+ export const DIST_BUILD_FAILURE_MARKER = ".specdojo-build-failed";
7
9
  /** 検証の沈黙した省略を避けるため、exec 系だけは警告ではなく中断する。 */
8
10
  const BLOCKING_COMMANDS = new Set(["exec"]);
9
11
  function findNewestFile(rootDir, extension) {
@@ -44,11 +46,13 @@ export function inspectBuildFreshness(packageRoot) {
44
46
  if (!newestDist) {
45
47
  return { status: "no-dist-output", packageRoot, newestSourcePath: newestSource.filePath };
46
48
  }
49
+ const buildFailed = existsSync(path.join(packageRoot, "dist", DIST_BUILD_FAILURE_MARKER));
47
50
  return {
48
- status: newestSource.mtimeMs > newestDist.mtimeMs ? "stale" : "up-to-date",
51
+ status: buildFailed || newestSource.mtimeMs > newestDist.mtimeMs ? "stale" : "up-to-date",
49
52
  packageRoot,
50
53
  newestSourcePath: newestSource.filePath,
51
54
  newestDistPath: newestDist.filePath,
55
+ ...(buildFailed ? { buildFailed: true } : {}),
52
56
  };
53
57
  }
54
58
  /**
@@ -77,7 +81,9 @@ function toDisplayPath(packageRoot, filePath) {
77
81
  function buildMessage(result, isBlocking) {
78
82
  const detail = result.status === "no-dist-output"
79
83
  ? "dist/ が存在しない"
80
- : `src が dist より新しい (src: ${toDisplayPath(result.packageRoot, result.newestSourcePath)}, dist: ${toDisplayPath(result.packageRoot, result.newestDistPath)})`;
84
+ : result.buildFailed
85
+ ? "直前の統合後ビルドが失敗した"
86
+ : `src が dist より新しい (src: ${toDisplayPath(result.packageRoot, result.newestSourcePath)}, dist: ${toDisplayPath(result.packageRoot, result.newestDistPath)})`;
81
87
  const head = isBlocking
82
88
  ? `specdojo: 中断: dist ビルドが古い: ${detail}`
83
89
  : `specdojo: 警告: dist ビルドが古い: ${detail}`;
@@ -0,0 +1,20 @@
1
+ import { createRequire } from "node:module";
2
+ import { extname } from "node:path";
3
+ import { load } from "./yaml.js";
4
+ const require = createRequire(import.meta.url);
5
+ const yamlMetadata = require("../../docs/specdojo/lib/yaml-metadata.cjs");
6
+ export function isYamlDocument(path) {
7
+ return [".yaml", ".yml"].includes(extname(path).toLowerCase());
8
+ }
9
+ export function isGradeDocument(path) {
10
+ return extname(path).toLowerCase() === ".md" || isYamlDocument(path);
11
+ }
12
+ export function readYamlMetadata(content, path) {
13
+ const metadata = yamlMetadata(load(content));
14
+ for (const key of ["id", "type", "status", "rulebook"]) {
15
+ if (typeof metadata?.[key] !== "string" || !metadata[key].trim()) {
16
+ throw new Error(`${path}: YAML grade target requires metadata ${key} at the root or x-spec-meta`);
17
+ }
18
+ }
19
+ return metadata;
20
+ }
@@ -0,0 +1,20 @@
1
+ export function isFindingCause(value) {
2
+ if (typeof value !== "object" || value === null || Array.isArray(value))
3
+ return false;
4
+ const cause = value;
5
+ if (cause.type === "document")
6
+ return Object.keys(cause).length === 1;
7
+ return (cause.type === "kata" &&
8
+ typeof cause.kind === "string" &&
9
+ ["rulebook", "recipe", "sample", "template"].includes(cause.kind) &&
10
+ typeof cause.location === "string" &&
11
+ cause.location.trim().length > 0 &&
12
+ Object.keys(cause).every((key) => ["type", "kind", "location"].includes(key)));
13
+ }
14
+ /** Legacy findings without a cause belong to the document. */
15
+ export function findingCause(finding) {
16
+ const cause = finding.cause;
17
+ return cause?.type === "kata"
18
+ ? { type: "kata", kind: cause.kind, location: cause.location }
19
+ : { type: "document" };
20
+ }
@@ -0,0 +1,48 @@
1
+ // SpecDojo が所有する Markdown frontmatter は `specdojo:` 名前空間配下に置く
2
+ // (document-metadata-standard.md)。他フレームワークの frontmatter キーとの衝突を避け、
3
+ // トップレベルを第三者ツールへ明け渡すための共通ユーティリティ。
4
+ //
5
+ // 対象は Markdown frontmatter のみ。独立 YAML データファイル(dct-*.yaml / pm-*.yaml /
6
+ // sch-*.yaml など)は名前空間化しないため、本モジュールは使わない。
7
+ import { load } from "./yaml.js";
8
+ const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
9
+ function specdojoFromBlock(block) {
10
+ let parsed;
11
+ try {
12
+ parsed = load(block);
13
+ }
14
+ catch {
15
+ return {};
16
+ }
17
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
18
+ return {};
19
+ const namespace = parsed.specdojo;
20
+ if (!namespace || typeof namespace !== "object" || Array.isArray(namespace))
21
+ return {};
22
+ return namespace;
23
+ }
24
+ // Markdown 文書先頭の frontmatter から `specdojo:` 名前空間オブジェクトを取り出す。
25
+ // frontmatter が無い / 解析不能 / `specdojo:` を欠く場合は空オブジェクトを返す。
26
+ export function readSpecdojoNamespace(content) {
27
+ const match = content.match(FRONTMATTER_RE);
28
+ if (!match)
29
+ return {};
30
+ return specdojoFromBlock(match[1]);
31
+ }
32
+ // readSpecdojoNamespace と同じだが、frontmatter に続く本文も返す(read-modify-write 用)。
33
+ export function parseSpecdojoDocument(content) {
34
+ const match = content.match(FRONTMATTER_RE);
35
+ if (!match)
36
+ return { data: {}, body: content };
37
+ return { data: specdojoFromBlock(match[1]), body: match[2] ?? "" };
38
+ }
39
+ // トップレベルの `key: value` 行群を `specdojo:` 配下へ字下げし、`---` で囲んだ
40
+ // frontmatter ブロック文字列にして返す。frontmatter を生成する各所で使う。
41
+ export function buildSpecdojoFrontmatter(innerLines) {
42
+ return [
43
+ "---",
44
+ "specdojo:",
45
+ ...innerLines.map((line) => (line.length === 0 ? "" : ` ${line}`)),
46
+ "---",
47
+ ].join("\n");
48
+ }
@@ -1,3 +1,4 @@
1
+ import { gitLockEnvironment } from "./cross-process-lock.js";
1
2
  export const GIT_LOCAL_ENV_VARS = [
2
3
  "GIT_ALTERNATE_OBJECT_DIRECTORIES",
3
4
  "GIT_COMMON_DIR",
@@ -17,7 +18,7 @@ export function removeGitLocalEnvironment(environment) {
17
18
  delete environment[name];
18
19
  }
19
20
  export function gitEnvironment() {
20
- const environment = { ...process.env };
21
+ const environment = { ...process.env, ...gitLockEnvironment() };
21
22
  removeGitLocalEnvironment(environment);
22
23
  return environment;
23
24
  }
@@ -1,5 +1,5 @@
1
1
  import { spawnSync } from "node:child_process";
2
- import { appendFileSync, lstatSync, mkdirSync } from "node:fs";
2
+ import { appendFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, } from "node:fs";
3
3
  import { dirname, join, relative, resolve, sep } from "node:path";
4
4
  import { gitEnvironment } from "./git-environment.js";
5
5
  import { redactSensitiveText, stripTerminalControlSequences } from "./text.js";
@@ -10,9 +10,27 @@ export { GIT_LOCAL_ENV_VARS, gitEnvironment } from "./git-environment.js";
10
10
  // for that lock, surfacing as "Unable to create '.../index.lock'". A failed lock acquisition
11
11
  // happens before git mutates anything, so retrying the same command is safe and idempotent.
12
12
  // 並行の run の統合や記帳と重なると、ロックは数百ミリ秒より長く保持される(PJR-G90K)。
13
- // 1.5 秒間隔で 10 回までやり直し、ロックのファイルは消さない(実際に動いている git がありうる)。
13
+ // 手の commit の pre-commit hook が負荷の下で十数分ロックを握ることもあるため(PJR-964D)、
14
+ // 最初の 10 回は 1.5 秒間隔、その後は 5 秒間隔で、既定 20 分まで解放を待つ。
15
+ // ロックのファイルは消さない(実際に動いている git がありうる)。
14
16
  export const INDEX_LOCK_RETRY_ATTEMPTS = 10;
15
17
  export const INDEX_LOCK_RETRY_WAIT_MS = 1500;
18
+ export const INDEX_LOCK_LONG_RETRY_WAIT_MS = 5000;
19
+ export const DEFAULT_INDEX_LOCK_WAIT_MS = 20 * 60 * 1000;
20
+ // 待っている間の告知の間隔。最初の取り合いで 1 回告げ、その後はこの間隔で経過を出す。
21
+ export const INDEX_LOCK_PROGRESS_INTERVAL_MS = 30 * 1000;
22
+ let configuredIndexLockWaitMilliseconds = DEFAULT_INDEX_LOCK_WAIT_MS;
23
+ // exec-defaults の `run.git_index_lock_wait_seconds` を、この process の git 操作へ反映する。
24
+ // src/shared は exec を import できないため、exec 側の設定の読み込みから値を渡す。
25
+ export function configureIndexLockWait(milliseconds = DEFAULT_INDEX_LOCK_WAIT_MS) {
26
+ if (!Number.isFinite(milliseconds) || milliseconds < 0) {
27
+ throw new Error(`index.lock wait must be a non-negative number of milliseconds: ${milliseconds}`);
28
+ }
29
+ configuredIndexLockWaitMilliseconds = milliseconds;
30
+ }
31
+ export function indexLockWaitMilliseconds() {
32
+ return configuredIndexLockWaitMilliseconds;
33
+ }
16
34
  // dubious ownership と、`.git` がある cwd での not-a-repository は一時的に起き、すぐの
17
35
  // 再試行では収まらないことがある(並行実行中の統合段で確認した)。両方で上限を共有する。
18
36
  const TRANSIENT_GIT_RETRY_DELAYS_MS = [2000, 5000, 10000];
@@ -47,6 +65,60 @@ export function isGitNotRepositoryWithGitMetadata(stderr, repoRoot) {
47
65
  function sleepSync(milliseconds) {
48
66
  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
49
67
  }
68
+ // 待つのをやめた理由を stderr の末尾へ足す。formatGitCommandFailure の要約は error 行を拾う。
69
+ function appendStderr(result, line) {
70
+ const stderr = typeof result.stderr === "string" ? result.stderr : "";
71
+ const separator = stderr === "" || stderr.endsWith("\n") ? "" : "\n";
72
+ return { ...result, stderr: `${stderr}${separator}${line}\n` };
73
+ }
74
+ export function formatWaitDuration(milliseconds) {
75
+ const totalSeconds = Math.round(milliseconds / 1000);
76
+ const minutes = Math.floor(totalSeconds / 60);
77
+ const seconds = totalSeconds % 60;
78
+ if (minutes === 0)
79
+ return `${seconds}s`;
80
+ return seconds === 0 ? `${minutes}m` : `${minutes}m${seconds}s`;
81
+ }
82
+ // 告知の分母。短い間隔の回数に、残りの時間を長い間隔で割った回数を足す。
83
+ function indexLockMaxAttempts(limitMilliseconds) {
84
+ const shortPhase = INDEX_LOCK_RETRY_ATTEMPTS * INDEX_LOCK_RETRY_WAIT_MS;
85
+ if (limitMilliseconds <= shortPhase) {
86
+ return Math.max(1, Math.ceil(limitMilliseconds / INDEX_LOCK_RETRY_WAIT_MS));
87
+ }
88
+ return (INDEX_LOCK_RETRY_ATTEMPTS +
89
+ Math.ceil((limitMilliseconds - shortPhase) / INDEX_LOCK_LONG_RETRY_WAIT_MS));
90
+ }
91
+ // Linux の /proc から、名前が git のプロセスが 1 つでも動いているかを調べる。どのプロセスが
92
+ // ロックを握るかを git は記録しないため、git が 1 つも動いていないときだけ「握り手がいない」と
93
+ // みなす(hook を実行中の git commit も git として残る)。/proc を読めない環境では undefined。
94
+ export function hasRunningGitProcess(procRoot = "/proc") {
95
+ let entries;
96
+ try {
97
+ entries = readdirSync(procRoot);
98
+ }
99
+ catch {
100
+ return undefined;
101
+ }
102
+ for (const entry of entries) {
103
+ if (!/^\d+$/.test(entry))
104
+ continue;
105
+ let name;
106
+ try {
107
+ name = readFileSync(join(procRoot, entry, "comm"), "utf8").trim();
108
+ }
109
+ catch {
110
+ // 調べている間に終了したプロセスは数えない。
111
+ continue;
112
+ }
113
+ if (name === "git" || name.startsWith("git-"))
114
+ return true;
115
+ }
116
+ return false;
117
+ }
118
+ // ロックのファイルが残っていて、git のプロセスが 1 つも動いていなければ古いロックとみなす。
119
+ export function isIndexLockOrphaned(lockPath, procRoot = "/proc") {
120
+ return existsSync(lockPath) && hasRunningGitProcess(procRoot) === false;
121
+ }
50
122
  export function transientGitFailureReason(stderr, repoRoot) {
51
123
  if (isGitDubiousOwnership(stderr))
52
124
  return "dubious ownership";
@@ -55,8 +127,13 @@ export function transientGitFailureReason(stderr, repoRoot) {
55
127
  }
56
128
  return undefined;
57
129
  }
58
- export function runGitWithTransientRetry(run, onTransientFailureRetry = () => undefined, sleep = sleepSync, repoRoot, recoverFromTransientFailure) {
130
+ export function runGitWithTransientRetry(run, onTransientFailureRetry = () => undefined, sleep = sleepSync, repoRoot, recoverFromTransientFailure, indexLockWait = {}) {
131
+ const limitMilliseconds = indexLockWait.limitMilliseconds ?? indexLockWaitMilliseconds();
132
+ const now = indexLockWait.now ?? Date.now;
133
+ const isLockOrphaned = indexLockWait.isLockOrphaned ?? isIndexLockOrphaned;
59
134
  let indexLockRetries = 0;
135
+ let indexLockStartedAt;
136
+ let nextProgressAt = 0;
60
137
  let transientFailureRetries = 0;
61
138
  let result = run();
62
139
  while (result.status !== 0) {
@@ -83,38 +160,72 @@ export function runGitWithTransientRetry(run, onTransientFailureRetry = () => un
83
160
  continue;
84
161
  }
85
162
  }
86
- if (indexLockRetries < INDEX_LOCK_RETRY_ATTEMPTS && isGitIndexLockContention(stderr)) {
87
- indexLockRetries += 1;
163
+ if (!isGitIndexLockContention(stderr))
164
+ break;
165
+ const lockPath = gitIndexLockPath(stderr);
166
+ indexLockStartedAt ??= now();
167
+ const elapsedMilliseconds = now() - indexLockStartedAt;
168
+ if (elapsedMilliseconds >= limitMilliseconds) {
169
+ return appendStderr(result, `error: index.lock was not released within ${formatWaitDuration(limitMilliseconds)}` +
170
+ " (run.git_index_lock_wait_seconds in exec-defaults)");
171
+ }
172
+ // 短い取り合いの間は古いロックか判断しない(git の起動と終了の合間に見えうる)。
173
+ if (indexLockRetries >= INDEX_LOCK_RETRY_ATTEMPTS && lockPath && isLockOrphaned(lockPath)) {
174
+ return appendStderr(result, `error: index.lock looks stale: no running git process holds ${lockPath}` +
175
+ ` after ${formatWaitDuration(elapsedMilliseconds)};` +
176
+ " remove it after confirming no git uses the repository");
177
+ }
178
+ const interval = indexLockRetries < INDEX_LOCK_RETRY_ATTEMPTS
179
+ ? INDEX_LOCK_RETRY_WAIT_MS
180
+ : INDEX_LOCK_LONG_RETRY_WAIT_MS;
181
+ const waitMilliseconds = Math.min(interval, limitMilliseconds - elapsedMilliseconds);
182
+ indexLockRetries += 1;
183
+ if (indexLockRetries === 1 || elapsedMilliseconds >= nextProgressAt) {
184
+ nextProgressAt =
185
+ (Math.floor(elapsedMilliseconds / INDEX_LOCK_PROGRESS_INTERVAL_MS) + 1) *
186
+ INDEX_LOCK_PROGRESS_INTERVAL_MS;
88
187
  onTransientFailureRetry({
89
188
  attempt: indexLockRetries,
90
- maxAttempts: INDEX_LOCK_RETRY_ATTEMPTS,
91
- waitMilliseconds: INDEX_LOCK_RETRY_WAIT_MS,
189
+ maxAttempts: indexLockMaxAttempts(limitMilliseconds),
190
+ waitMilliseconds,
92
191
  reason: "index.lock contention",
192
+ elapsedMilliseconds,
193
+ limitMilliseconds,
194
+ ...(lockPath ? { lockPath } : {}),
93
195
  });
94
- sleep(INDEX_LOCK_RETRY_WAIT_MS);
95
- result = run();
96
- continue;
97
196
  }
98
- break;
197
+ sleep(waitMilliseconds);
198
+ result = run();
99
199
  }
100
200
  return result;
101
201
  }
102
202
  // spawnSync の既定の maxBuffer(1 MiB)では、未追跡のファイルが多い作業場所の
103
203
  // `git status --porcelain` などが打ち切られ、子プロセスが SIGTERM で止められる。
104
204
  export const GIT_OUTPUT_MAX_BUFFER = 256 * 1024 * 1024;
105
- export function gitResult(repoRoot, args, recoverFromTransientFailure) {
205
+ export function gitResult(repoRoot, args, recoverFromTransientFailure,
206
+ // 隔離済みの Git 環境へ足す変数(統合の commit の LEFTHOOK_EXCLUDE など)。
207
+ extraEnv) {
106
208
  const cwd = resolve(repoRoot);
107
209
  const run = () => spawnSync("git", ["-C", cwd, ...args], {
108
210
  // `-C` だけに依存せず、子プロセス自体も対象 repository から起動する。linked worktree の
109
211
  // `.git` が相対 gitdir の場合も、resume 中の diff を runner の cwd から切り離す。
110
212
  cwd,
111
213
  encoding: "utf8",
112
- env: gitEnvironment(),
214
+ env: { ...gitEnvironment(), ...extraEnv },
113
215
  maxBuffer: GIT_OUTPUT_MAX_BUFFER,
114
216
  stdio: ["ignore", "pipe", "pipe"],
115
217
  });
116
- return runGitWithTransientRetry(run, ({ attempt, maxAttempts, waitMilliseconds, reason }) => {
218
+ return runGitWithTransientRetry(run, (notice) => {
219
+ const { attempt, maxAttempts, waitMilliseconds, reason } = notice;
117
220
  const summary = summarizeGitArguments(args);
221
+ if (notice.elapsedMilliseconds !== undefined && notice.limitMilliseconds !== undefined) {
222
+ const lock = notice.lockPath ? `, lock: ${notice.lockPath}` : "";
223
+ process.stderr.write("warning: waiting for index.lock to be released" +
224
+ ` (elapsed ${formatWaitDuration(notice.elapsedMilliseconds)}` +
225
+ ` / limit ${formatWaitDuration(notice.limitMilliseconds)}${lock}` +
226
+ `, cwd: ${repoRoot}${summary ? `, args: ${summary}` : ""})\n`);
227
+ return;
228
+ }
118
229
  process.stderr.write(`warning: git command failed with ${reason}; retrying in ${waitMilliseconds / 1000}s` +
119
230
  ` (attempt ${attempt}/${maxAttempts}, cwd: ${repoRoot}${summary ? `, args: ${summary}` : ""})\n`);
120
231
  }, sleepSync, cwd, recoverFromTransientFailure);
@@ -132,7 +243,9 @@ function abbreviate(value, limit) {
132
243
  export function summarizeGitArguments(args) {
133
244
  const separatorIndex = args.indexOf("--");
134
245
  const head = separatorIndex === -1 ? args : args.slice(0, separatorIndex);
135
- const parts = head.map((arg) => abbreviate(arg, MAX_GIT_ARGUMENT_LENGTH));
246
+ // 複数行の commit message などは 1 行へ畳む。改行が残ると要約が失敗理由の行から離れ、
247
+ // 出力の最後の行が引数の断片だけになって失敗に気づきにくい(PJR-Y3XS)。
248
+ const parts = head.map((arg) => abbreviate(arg.replace(/\s+/g, " ").trim(), MAX_GIT_ARGUMENT_LENGTH));
136
249
  if (separatorIndex !== -1) {
137
250
  const pathCount = args.length - separatorIndex - 1;
138
251
  parts.push(`-- ${pathCount} ${pathCount === 1 ? "path" : "paths"}`);
@@ -194,7 +307,11 @@ export function formatGitCommandFailure(args, stderr, processFailure = "") {
194
307
  // gitResult は index.lock の取り合いをやり直したうえで失敗を返す。どのロックが残っていたかを
195
308
  // 要約の切り詰めに左右されず先頭に残す(ロックは runner が消さないため、人が確かめる手掛かり)。
196
309
  const lockPath = isGitIndexLockContention(stderr) ? gitIndexLockPath(stderr) : undefined;
197
- const lockNotice = lockPath ? `index.lock is still held (lock: ${lockPath})` : "";
310
+ // 原因の候補: 手の commit などの hook がまだ動いている、または異常終了した git の古いロック。
311
+ const lockNotice = lockPath
312
+ ? `index.lock is still held (lock: ${lockPath};` +
313
+ " a git hook such as pre-commit may still be running, or a crashed git left a stale lock)"
314
+ : "";
198
315
  const cause = [processFailure.trim(), lockNotice, summarizeGitStderr(stderr)]
199
316
  .filter((part) => part !== "")
200
317
  .join(" / ");
@@ -352,3 +469,56 @@ export function unstageCommitTargets(repoRoot, paths) {
352
469
  return;
353
470
  gitOutput(repoRoot, ["reset", "--quiet", "--", ...unique]);
354
471
  }
472
+ // `git commit -- <pathspec>`(--only)は一時 index で commit する。pre-commit hook の整形と
473
+ // `git add`(lefthook の stage_fixed)は一時 index にだけ入り、本来の index には hook 前の内容が
474
+ // 残る。HEAD と作業ツリーは整形後で一致するのに、index だけが整形前を staged として持ち、次の統合を
475
+ // stagedMergeBlocker で止める(PJR-Y3XS)。commit 対象のうち作業ツリーが HEAD と一致するパスだけを
476
+ // HEAD へ戻す。作業ツリーが HEAD と異なるパスは、利用者の作業の可能性があるため触らない。
477
+ // 戻したパス(リポジトリルート起点)を返す。
478
+ export function restoreIndexAfterPathspecCommit(cwd, pathspecs, globals = []) {
479
+ if (pathspecs.length === 0)
480
+ return [];
481
+ const zeroSeparated = (output) => output.split("\0").filter(Boolean);
482
+ const staged = zeroSeparated(gitOutput(cwd, [
483
+ ...globals,
484
+ "diff",
485
+ "--cached",
486
+ "--no-renames",
487
+ "--no-relative",
488
+ "--name-only",
489
+ "-z",
490
+ "--",
491
+ ...pathspecs,
492
+ ]));
493
+ if (staged.length === 0)
494
+ return [];
495
+ const topLiteral = (path) => `:(top,literal)${path}`;
496
+ const differsFromHead = new Set(zeroSeparated(gitOutput(cwd, [
497
+ ...globals,
498
+ "diff",
499
+ "--no-renames",
500
+ "--no-relative",
501
+ "--name-only",
502
+ "-z",
503
+ "HEAD",
504
+ "--",
505
+ ...staged.map(topLiteral),
506
+ ])));
507
+ const restorable = staged.filter((path) => !differsFromHead.has(path));
508
+ if (restorable.length === 0)
509
+ return [];
510
+ gitOutput(cwd, [...globals, "reset", "--quiet", "--", ...restorable.map(topLiteral)]);
511
+ return restorable;
512
+ }
513
+ // A non-fast-forward merge requires a clean index even when staged paths do not overlap the
514
+ // incoming diff. Never reset or commit another operation's staged work on its behalf.
515
+ export function stagedMergeBlocker(repoRoot) {
516
+ const paths = gitOutput(repoRoot, ["diff", "--cached", "--no-renames", "--name-only", "-z"])
517
+ .split("\0")
518
+ .filter(Boolean);
519
+ if (paths.length === 0)
520
+ return undefined;
521
+ return (`Staged changes in integration target ${repoRoot}: ${paths.join(", ")}. ` +
522
+ `Commit them, or run git restore --staged -- <path> for each listed path in that worktree ` +
523
+ `(file contents are preserved), then retry integration.`);
524
+ }
@@ -1,7 +1,9 @@
1
+ import { isYamlDocument, readYamlMetadata } from "./document-metadata.js";
1
2
  import { createHash } from "node:crypto";
2
3
  import { existsSync, readFileSync, realpathSync } from "node:fs";
3
4
  import { isAbsolute, join, relative, resolve, sep } from "node:path";
4
5
  import { load } from "./yaml.js";
6
+ import { isFindingCause } from "./finding-cause.js";
5
7
  import { getProjectExecutionPath, loadConfig, resolveRepoRoot, specdojoRootDir, } from "./specdojo-config.js";
6
8
  const DOCUMENT_ID_RE = /^[a-z0-9][a-z0-9-:]*$/;
7
9
  export const SEVERITIES = ["blocker", "major", "minor", "note"];
@@ -23,6 +25,15 @@ export function markdownDocumentId(content, path) {
23
25
  }
24
26
  return id;
25
27
  }
28
+ export function gradeDocumentId(content, path) {
29
+ if (!isYamlDocument(path))
30
+ return markdownDocumentId(content, path);
31
+ const id = readYamlMetadata(content, path).id;
32
+ if (typeof id !== "string" || !DOCUMENT_ID_RE.test(id)) {
33
+ throw new Error(`${path}: YAML metadata id is required to store a grade result`);
34
+ }
35
+ return id;
36
+ }
26
37
  export function resolveGradeResultsDirectory(projectOption, rootDir = specdojoRootDir()) {
27
38
  const { config } = loadConfig(rootDir);
28
39
  if (!config)
@@ -66,7 +77,7 @@ export function gradeResultPathForDocument(opts) {
66
77
  const resultsDirectory = opts.resultsDirectory
67
78
  ? resolve(rootDir, opts.resultsDirectory)
68
79
  : resolveGradeResultsDirectory(opts.project, rootDir);
69
- return gradeResultPath(repo ? join(resultsDirectory, repo.name) : resultsDirectory, markdownDocumentId(content, opts.documentPath));
80
+ return gradeResultPath(repo ? join(resultsDirectory, repo.name) : resultsDirectory, gradeDocumentId(content, opts.documentPath));
70
81
  }
71
82
  export function parseGradeResult(content, path) {
72
83
  const parsed = load(content);
@@ -94,6 +105,11 @@ export function parseGradeResult(content, path) {
94
105
  Object.values(result.source_hashes).some((hash) => typeof hash !== "string" || !/^[a-f0-9]{64}$/.test(hash)))) {
95
106
  throw new Error(`${path}: source_hashes must map sources to SHA-256 hex digests`);
96
107
  }
108
+ for (const finding of result.findings) {
109
+ if (finding.cause !== undefined && !isFindingCause(finding.cause)) {
110
+ throw new Error(`${path}: invalid finding cause`);
111
+ }
112
+ }
97
113
  return result;
98
114
  }
99
115
  export function gradeFindingDisplayMessage(finding) {
@@ -16,6 +16,9 @@ function hasConfiguredPath(config, key) {
16
16
  }
17
17
  export function renderLefthookConfig(config) {
18
18
  const commands = [
19
+ " git-lock-warning:",
20
+ " run: node tools/specdojo-pre-commit.mjs git-lock-warning",
21
+ "",
19
22
  " prettier:",
20
23
  ' glob: "*.{md,yaml,yml}"',
21
24
  " run: node tools/specdojo-pre-commit.mjs prettier {staged_files}",