specdojo 0.8.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 (284) hide show
  1. package/.github/agents/specdojo-orchestrator.md +4 -1
  2. package/CHANGELOG.md +64 -0
  3. package/dist/catalog/catalog.js +16 -14
  4. package/dist/commands/agent.js +5 -3
  5. package/dist/commands/build.js +69 -10
  6. package/dist/commands/git.js +206 -0
  7. package/dist/commands/init.js +4 -2
  8. package/dist/commands/where.js +25 -0
  9. package/dist/dashboard/dashboard.js +5 -3
  10. package/dist/dashboard/routines.js +4 -7
  11. package/dist/dashboard/timeline.js +14 -14
  12. package/dist/docs/index-command.js +2 -2
  13. package/dist/docs/yaml-business-tables.js +243 -0
  14. package/dist/docs/yaml-interface-tables.js +106 -0
  15. package/dist/docs/yaml-pages-command.js +5 -3
  16. package/dist/docs/yaml-pages.js +146 -3
  17. package/dist/docs/yaml-table-shared.js +70 -0
  18. package/dist/docs/yaml-tables.js +39 -0
  19. package/dist/exec/agent-config.js +9 -0
  20. package/dist/exec/agent-protected-config.js +2 -0
  21. package/dist/exec/commands.js +31 -18
  22. package/dist/exec/events.js +34 -14
  23. package/dist/exec/evidence.js +13 -3
  24. package/dist/exec/parent-validation.js +56 -3
  25. package/dist/exec/plans-core.js +21 -2
  26. package/dist/exec/plans-generation.js +6 -7
  27. package/dist/exec/post-integration.js +162 -0
  28. package/dist/exec/queue-command.js +166 -0
  29. package/dist/exec/queue.js +285 -0
  30. package/dist/exec/register-foreign-wait.js +84 -0
  31. package/dist/exec/repo-integration-sync.js +17 -5
  32. package/dist/exec/reporter.js +2 -2
  33. package/dist/exec/results.js +24 -4
  34. package/dist/exec/review-kata.js +4 -1
  35. package/dist/exec/run/agent-pipeline.js +3 -2
  36. package/dist/exec/run/agent.js +12 -6
  37. package/dist/exec/run/change-scope.js +365 -0
  38. package/dist/exec/run/deferred-cleanup.js +31 -0
  39. package/dist/exec/run/in-place.js +4 -1
  40. package/dist/exec/run/job-lock.js +66 -0
  41. package/dist/exec/run/job-sequence.js +137 -0
  42. package/dist/exec/run/job.js +56 -19
  43. package/dist/exec/run/lifecycle-commands.js +1 -1
  44. package/dist/exec/run/lock.js +22 -1
  45. package/dist/exec/run/register-command.js +8 -5
  46. package/dist/exec/run/register-mode.js +68 -8
  47. package/dist/exec/run/register-resume.js +68 -14
  48. package/dist/exec/run/register-state.js +13 -8
  49. package/dist/exec/run/register-worktree.js +140 -125
  50. package/dist/exec/run/schedule-mode.js +75 -14
  51. package/dist/exec/run/schedule-prepare.js +3 -0
  52. package/dist/exec/run/schedule-task.js +88 -38
  53. package/dist/exec/run/shared.js +5 -0
  54. package/dist/exec/schedule/schedule.js +116 -4
  55. package/dist/exec/shared.js +1 -1
  56. package/dist/exec/smoke.js +190 -0
  57. package/dist/exec/strategy.js +13 -3
  58. package/dist/exec/task-view.js +6 -4
  59. package/dist/exec/trial-commands.js +5 -2
  60. package/dist/exec/trial-core.js +6 -1
  61. package/dist/exec/validation-metrics.js +181 -0
  62. package/dist/exec/worktree-cleanup-lock.js +26 -0
  63. package/dist/exec/worktree-command.js +9 -1
  64. package/dist/exec/worktree-ops-commit.js +2 -2
  65. package/dist/exec/worktree.js +13 -2
  66. package/dist/grade/command-apply.js +3 -3
  67. package/dist/grade/command-inspect.js +5 -3
  68. package/dist/grade/command-plan.js +1 -1
  69. package/dist/grade/command-run.js +5 -1
  70. package/dist/grade/run.js +64 -8
  71. package/dist/job/definition.js +84 -8
  72. package/dist/job/job.js +79 -23
  73. package/dist/register/authoring-sources.js +22 -16
  74. package/dist/register/maintenance-commands.js +2 -2
  75. package/dist/register/register.js +31 -7
  76. package/dist/routine/definition.js +9 -0
  77. package/dist/routine/routine.js +137 -43
  78. package/dist/routine/status.js +62 -0
  79. package/dist/schedule/schedule.js +38 -39
  80. package/dist/shared/agent-types.js +5 -0
  81. package/dist/shared/cross-process-lock.js +9 -1
  82. package/dist/shared/dist-freshness.js +8 -2
  83. package/dist/shared/git-environment.js +2 -1
  84. package/dist/shared/git.js +44 -1
  85. package/dist/shared/lefthook-scaffold.js +3 -0
  86. package/dist/shared/local-config.js +244 -0
  87. package/dist/shared/specdojo-config.js +34 -20
  88. package/dist/shared/specdojo-gitignore.js +1 -0
  89. package/dist/shared/text.js +9 -1
  90. package/dist/shared/where-alias.js +13 -0
  91. package/dist/specdojo.js +4 -0
  92. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +2 -0
  93. package/docs/ja/specdojo/guides/exec-config-guide.md +23 -4
  94. package/docs/ja/specdojo/guides/exec-operation-guide.md +44 -1
  95. package/docs/ja/specdojo/guides/job-sequence-guide.md +77 -0
  96. package/docs/ja/specdojo/guides/quick-start-guide.md +3 -3
  97. package/docs/ja/specdojo/guides/register-operation-guide.md +1 -1
  98. package/docs/ja/specdojo/guides/routine-operation-guide.md +11 -6
  99. package/docs/ja/specdojo/guides/schedule-design-guide.md +20 -17
  100. package/docs/ja/specdojo/guides/waza-guide.md +12 -8
  101. package/docs/ja/specdojo/recipes/bac-recipe.md +66 -49
  102. package/docs/ja/specdojo/recipes/bes-recipe.md +90 -54
  103. package/docs/ja/specdojo/recipes/bps-recipe.md +88 -139
  104. package/docs/ja/specdojo/recipes/br-recipe.md +40 -47
  105. package/docs/ja/specdojo/recipes/cdfd-overview-recipe.md +97 -109
  106. package/docs/ja/specdojo/recipes/cdfd-recipe.md +85 -146
  107. package/docs/ja/specdojo/recipes/cdfd-uc-recipe.md +91 -110
  108. package/docs/ja/specdojo/recipes/cnd-recipe.md +79 -69
  109. package/docs/ja/specdojo/recipes/cpd-recipe.md +78 -64
  110. package/docs/ja/specdojo/recipes/cxd-recipe.md +92 -75
  111. package/docs/ja/specdojo/recipes/ifd-recipe.md +79 -68
  112. package/docs/ja/specdojo/recipes/ifx-cmd-recipe.md +78 -105
  113. package/docs/ja/specdojo/recipes/ifx-index-recipe.md +105 -71
  114. package/docs/ja/specdojo/recipes/pm-communication-plan-recipe.md +60 -49
  115. package/docs/ja/specdojo/recipes/pm-members-recipe.md +50 -51
  116. package/docs/ja/specdojo/recipes/pm-organization-recipe.md +59 -51
  117. package/docs/ja/specdojo/recipes/pm-plan-recipe.md +69 -56
  118. package/docs/ja/specdojo/recipes/pm-quality-management-plan-recipe.md +37 -56
  119. package/docs/ja/specdojo/recipes/pm-raci-recipe.md +39 -53
  120. package/docs/ja/specdojo/recipes/pm-roles-recipe.md +52 -79
  121. package/docs/ja/specdojo/recipes/prj-assumptions-constraints-dependencies-recipe.md +64 -93
  122. package/docs/ja/specdojo/recipes/prj-charter-recipe.md +71 -106
  123. package/docs/ja/specdojo/recipes/prj-comparison-of-alternatives-recipe.md +78 -157
  124. package/docs/ja/specdojo/recipes/prj-issues-and-approach-recipe.md +62 -111
  125. package/docs/ja/specdojo/recipes/prj-scope-recipe.md +67 -123
  126. package/docs/ja/specdojo/recipes/prj-stakeholder-register-recipe.md +60 -96
  127. package/docs/ja/specdojo/recipes/prj-success-criteria-and-acceptance-criteria-recipe.md +61 -105
  128. package/docs/ja/specdojo/recipes/stsd-recipe.md +79 -109
  129. package/docs/ja/specdojo/recipes/sysd-critical-flows-recipe.md +78 -55
  130. package/docs/ja/specdojo/recipes/sysd-cross-cutting-policy-recipe.md +82 -73
  131. package/docs/ja/specdojo/recipes/sysd-index-recipe.md +78 -59
  132. package/docs/ja/specdojo/recipes/tsd-recipe.md +149 -129
  133. package/docs/ja/specdojo/references/command-reference.md +257 -117
  134. package/docs/ja/specdojo/references/deliverables-reference.md +21 -12
  135. package/docs/ja/specdojo/references/specdojo-config-reference.md +37 -2
  136. package/docs/ja/specdojo/rulebooks/atc-index-rulebook.md +101 -257
  137. package/docs/ja/specdojo/rulebooks/atc-rulebook.md +102 -228
  138. package/docs/ja/specdojo/rulebooks/bac-rulebook.md +19 -28
  139. package/docs/ja/specdojo/rulebooks/bdd-rulebook.md +16 -67
  140. package/docs/ja/specdojo/rulebooks/bds-rulebook.md +30 -51
  141. package/docs/ja/specdojo/rulebooks/bes-index-rulebook.md +41 -61
  142. package/docs/ja/specdojo/rulebooks/bes-rulebook.md +22 -50
  143. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +24 -56
  144. package/docs/ja/specdojo/rulebooks/br-rulebook.md +13 -38
  145. package/docs/ja/specdojo/rulebooks/ccd-mermaid-rulebook.md +41 -76
  146. package/docs/ja/specdojo/rulebooks/cdfd-d2-rulebook.md +18 -93
  147. package/docs/ja/specdojo/rulebooks/cdfd-mermaid-rulebook.md +18 -52
  148. package/docs/ja/specdojo/rulebooks/cdfd-overview-rulebook.md +109 -147
  149. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +80 -108
  150. package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +21 -46
  151. package/docs/ja/specdojo/rulebooks/cdr-rulebook.md +144 -0
  152. package/docs/ja/specdojo/rulebooks/cdsd-rulebook.md +27 -48
  153. package/docs/ja/specdojo/rulebooks/cdt-rulebook.md +37 -50
  154. package/docs/ja/specdojo/rulebooks/clis-rulebook.md +52 -69
  155. package/docs/ja/specdojo/rulebooks/cnd-mermaid-rulebook.md +33 -86
  156. package/docs/ja/specdojo/rulebooks/cnd-rulebook.md +16 -32
  157. package/docs/ja/specdojo/rulebooks/cop-index-rulebook.md +45 -131
  158. package/docs/ja/specdojo/rulebooks/cop-rulebook.md +69 -275
  159. package/docs/ja/specdojo/rulebooks/cpd-mermaid-rulebook.md +20 -112
  160. package/docs/ja/specdojo/rulebooks/cpd-rulebook.md +23 -56
  161. package/docs/ja/specdojo/rulebooks/cxd-mermaid-rulebook.md +12 -145
  162. package/docs/ja/specdojo/rulebooks/cxd-rulebook.md +39 -47
  163. package/docs/ja/specdojo/rulebooks/dct-index-rulebook.md +37 -56
  164. package/docs/ja/specdojo/rulebooks/dct-rulebook.md +118 -175
  165. package/docs/ja/specdojo/rulebooks/dec-rulebook.md +5 -14
  166. package/docs/ja/specdojo/rulebooks/dmd-index-rulebook.md +22 -66
  167. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +36 -94
  168. package/docs/ja/specdojo/rulebooks/dss-rulebook.md +59 -81
  169. package/docs/ja/specdojo/rulebooks/etc-index-rulebook.md +31 -131
  170. package/docs/ja/specdojo/rulebooks/etc-rulebook.md +50 -104
  171. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +51 -61
  172. package/docs/ja/specdojo/rulebooks/ifd-mermaid-rulebook.md +38 -45
  173. package/docs/ja/specdojo/rulebooks/ifx-api-rulebook.md +14 -20
  174. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +26 -38
  175. package/docs/ja/specdojo/rulebooks/ifx-file-rulebook.md +26 -107
  176. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +42 -49
  177. package/docs/ja/specdojo/rulebooks/ifx-msg-rulebook.md +14 -22
  178. package/docs/ja/specdojo/rulebooks/imp-business-rulebook.md +21 -44
  179. package/docs/ja/specdojo/rulebooks/imp-data-rulebook.md +41 -64
  180. package/docs/ja/specdojo/rulebooks/imp-interface-rulebook.md +14 -38
  181. package/docs/ja/specdojo/rulebooks/imp-operations-rulebook.md +34 -61
  182. package/docs/ja/specdojo/rulebooks/imp-test-rulebook.md +27 -50
  183. package/docs/ja/specdojo/rulebooks/itc-index-rulebook.md +70 -199
  184. package/docs/ja/specdojo/rulebooks/itc-rulebook.md +65 -153
  185. package/docs/ja/specdojo/rulebooks/mip-index-rulebook.md +74 -150
  186. package/docs/ja/specdojo/rulebooks/mm-rulebook.md +11 -23
  187. package/docs/ja/specdojo/rulebooks/mtp-rulebook.md +99 -176
  188. package/docs/ja/specdojo/rulebooks/nfr-availability-rulebook.md +35 -61
  189. package/docs/ja/specdojo/rulebooks/nfr-index-rulebook.md +75 -117
  190. package/docs/ja/specdojo/rulebooks/nfr-integrity-rulebook.md +31 -60
  191. package/docs/ja/specdojo/rulebooks/nfr-maintainability-rulebook.md +26 -81
  192. package/docs/ja/specdojo/rulebooks/nfr-operations-rulebook.md +32 -70
  193. package/docs/ja/specdojo/rulebooks/nfr-performance-rulebook.md +45 -87
  194. package/docs/ja/specdojo/rulebooks/nfr-reliability-rulebook.md +48 -101
  195. package/docs/ja/specdojo/rulebooks/nfr-security-safety-rulebook.md +44 -80
  196. package/docs/ja/specdojo/rulebooks/nfr-usability-rulebook.md +59 -127
  197. package/docs/ja/specdojo/rulebooks/opd-index-rulebook.md +31 -50
  198. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +42 -109
  199. package/docs/ja/specdojo/rulebooks/opr-index-rulebook.md +29 -42
  200. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +29 -87
  201. package/docs/ja/specdojo/rulebooks/otp-index-rulebook.md +62 -84
  202. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +11 -61
  203. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +91 -106
  204. package/docs/ja/specdojo/rulebooks/pm-change-request-log-rulebook.md +25 -34
  205. package/docs/ja/specdojo/rulebooks/pm-communication-plan-rulebook.md +30 -53
  206. package/docs/ja/specdojo/rulebooks/pm-issue-log-rulebook.md +23 -35
  207. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +27 -45
  208. package/docs/ja/specdojo/rulebooks/pm-organization-rulebook.md +37 -45
  209. package/docs/ja/specdojo/rulebooks/pm-plan-rulebook.md +45 -46
  210. package/docs/ja/specdojo/rulebooks/pm-quality-management-plan-rulebook.md +37 -48
  211. package/docs/ja/specdojo/rulebooks/pm-raci-rulebook.md +25 -29
  212. package/docs/ja/specdojo/rulebooks/pm-risk-register-rulebook.md +28 -35
  213. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +36 -41
  214. package/docs/ja/specdojo/rulebooks/pr-rulebook.md +5 -18
  215. package/docs/ja/specdojo/rulebooks/prj-assumptions-constraints-dependencies-rulebook.md +16 -37
  216. package/docs/ja/specdojo/rulebooks/prj-charter-rulebook.md +23 -97
  217. package/docs/ja/specdojo/rulebooks/prj-comparison-of-alternatives-rulebook.md +39 -57
  218. package/docs/ja/specdojo/rulebooks/prj-issues-and-approach-rulebook.md +43 -116
  219. package/docs/ja/specdojo/rulebooks/prj-scope-rulebook.md +16 -51
  220. package/docs/ja/specdojo/rulebooks/prj-stakeholder-register-rulebook.md +47 -92
  221. package/docs/ja/specdojo/rulebooks/prj-success-criteria-and-acceptance-criteria-rulebook.md +25 -84
  222. package/docs/ja/specdojo/rulebooks/sac-rulebook.md +44 -107
  223. package/docs/ja/specdojo/rulebooks/sf-index-rulebook.md +39 -49
  224. package/docs/ja/specdojo/rulebooks/sf-rulebook.md +42 -49
  225. package/docs/ja/specdojo/rulebooks/sld-rulebook.md +64 -89
  226. package/docs/ja/specdojo/rulebooks/stc-index-rulebook.md +90 -189
  227. package/docs/ja/specdojo/rulebooks/stc-rulebook.md +45 -105
  228. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +6 -12
  229. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +49 -68
  230. package/docs/ja/specdojo/rulebooks/sysd-critical-flows-rulebook.md +51 -60
  231. package/docs/ja/specdojo/rulebooks/sysd-cross-cutting-policy-rulebook.md +46 -50
  232. package/docs/ja/specdojo/rulebooks/sysd-index-rulebook.md +39 -64
  233. package/docs/ja/specdojo/rulebooks/sysd-rulebook.md +47 -60
  234. package/docs/ja/specdojo/rulebooks/trc-requirements-to-specs-rulebook.md +69 -70
  235. package/docs/ja/specdojo/rulebooks/trc-requirements-to-tests-rulebook.md +65 -72
  236. package/docs/ja/specdojo/rulebooks/tsd-index-rulebook.md +35 -46
  237. package/docs/ja/specdojo/rulebooks/tsd-rulebook.md +49 -66
  238. package/docs/ja/specdojo/rulebooks/tsp-index-rulebook.md +64 -139
  239. package/docs/ja/specdojo/rulebooks/uis-rulebook.md +41 -108
  240. package/docs/ja/specdojo/rulebooks/utc-index-rulebook.md +49 -144
  241. package/docs/ja/specdojo/rulebooks/utc-rulebook.md +67 -155
  242. package/docs/ja/specdojo/samples/bds-sample.md +58 -71
  243. package/docs/ja/specdojo/samples/bes-index-sample.md +20 -37
  244. package/docs/ja/specdojo/samples/bes-sample.md +43 -53
  245. package/docs/ja/specdojo/samples/bps-sample.md +42 -54
  246. package/docs/ja/specdojo/samples/br-sample.md +40 -52
  247. package/docs/ja/specdojo/samples/ccd-sample.md +0 -1
  248. package/docs/ja/specdojo/samples/cdr-sample.md +78 -0
  249. package/docs/ja/specdojo/samples/cdsd-sample.md +47 -63
  250. package/docs/ja/specdojo/samples/clis-sample.md +70 -77
  251. package/docs/ja/specdojo/samples/dec-sample.md +2 -3
  252. package/docs/ja/specdojo/samples/ifx-api-sample.yaml +0 -2
  253. package/docs/ja/specdojo/samples/ifx-msg-sample.yaml +0 -2
  254. package/docs/ja/specdojo/samples/job-sequence.yaml +67 -0
  255. package/docs/ja/specdojo/samples/mip-index-sample.md +98 -20
  256. package/docs/ja/specdojo/samples/pm-communication-plan-sample.md +26 -19
  257. package/docs/ja/specdojo/samples/pm-organization-sample.md +39 -50
  258. package/docs/ja/specdojo/samples/pm-plan-sample.md +61 -67
  259. package/docs/ja/specdojo/samples/pm-quality-management-plan-sample.md +31 -45
  260. package/docs/ja/specdojo/samples/pm-raci-sample.md +31 -37
  261. package/docs/ja/specdojo/samples/prj-assumptions-constraints-dependencies-sample.md +32 -48
  262. package/docs/ja/specdojo/samples/prj-charter-sample.md +42 -59
  263. package/docs/ja/specdojo/samples/prj-comparison-of-alternatives-sample.md +55 -61
  264. package/docs/ja/specdojo/samples/prj-success-criteria-and-acceptance-criteria-sample.md +30 -33
  265. package/docs/ja/specdojo/samples/sf-index-sample.md +13 -55
  266. package/docs/ja/specdojo/samples/sf-sample.md +73 -85
  267. package/docs/ja/specdojo/samples/sld-sample.md +60 -79
  268. package/docs/ja/specdojo/samples/uis-sample.md +98 -121
  269. package/docs/ja/specdojo/standards/job-definition-standard.md +24 -9
  270. package/docs/ja/specdojo/templates/cdr-template.md +58 -0
  271. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +2 -1
  272. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +42 -5
  273. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +35 -0
  274. package/docs/specdojo/schemas/v1/job-run.schema.yaml +23 -0
  275. package/docs/specdojo/schemas/v1/job.schema.yaml +63 -2
  276. package/docs/specdojo/schemas/v1/sch-strategy.schema.yaml +2 -2
  277. package/package.json +9 -6
  278. package/templates/antigravity/orchestrator.md +4 -1
  279. package/templates/claude/agents/specdojo-orchestrator.md +4 -1
  280. package/templates/codex/agents/specdojo-orchestrator.toml +4 -1
  281. package/templates/codex/orchestrator.md +4 -1
  282. package/templates/init-exec-defaults.yaml +13 -0
  283. package/templates/lefthook/tools/specdojo-pre-commit.mjs +8 -0
  284. package/templates/opencode/agents/specdojo-orchestrator.md +5 -2
@@ -36,6 +36,7 @@ async function runOneTrial(params) {
36
36
  const parentValidationStartedAt = Date.now();
37
37
  const parentValidationBatch = await runConfiguredParentValidationBatch(params.execDefaults, worktree.path, {
38
38
  label: `${params.record.task_id} (${trial.trial_id})`,
39
+ metricsPath: join(comparisonDir(params.executionPath, params.record.comparison_id), "trials", trial.trial_id, "parent-validation-metrics.jsonl"),
39
40
  });
40
41
  parentValidations = parentValidationBatch.validations;
41
42
  parentValidationFailureOutputs = parentValidationBatch.failureOutputs;
@@ -93,7 +94,7 @@ async function runOneTrial(params) {
93
94
  evidence: reporterEvidence,
94
95
  mode: parsePlanTaskIdentity(params.plan)?.mode ?? "edit",
95
96
  invoke: async (reporterPrompt) => {
96
- const reporterOutcome = await spawnAgent(params.reporterCommand, reporterPrompt, worktree.path, worktreeEnvironment(params.repoRoot, worktree.path, params.schedulePath, params.executionPath));
97
+ const reporterOutcome = await spawnAgent(params.reporterCommand, reporterPrompt, worktree.path, worktreeEnvironment(params.repoRoot, worktree.path, params.schedulePath, params.executionPath), "reporter");
97
98
  const result = reporterOutcome.exitCode === 0
98
99
  ? "success"
99
100
  : isRateLimitError(reporterOutcome.exitCode, `${reporterOutcome.stdout}\n${reporterOutcome.stderr}`, params.reporterRateLimitDetection)
@@ -477,7 +478,9 @@ function commandError(error) {
477
478
  process.exitCode = 1;
478
479
  }
479
480
  export function registerExecTrialCommands(exec) {
480
- const trial = exec.command("trial").description("Compare multiple agents on one immutable plan");
481
+ const trial = exec
482
+ .command("trial", { hidden: true })
483
+ .description("Compare multiple agents on one immutable plan");
481
484
  trial
482
485
  .command("run")
483
486
  .requiredOption("--project <projectId>", "Project id")
@@ -1,10 +1,12 @@
1
1
  import { spawn } from "node:child_process";
2
+ import { trackExecutor } from "./validation-metrics.js";
2
3
  import { createHash, randomUUID } from "node:crypto";
3
4
  import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
4
5
  import { dirname, join, relative, resolve, sep } from "node:path";
5
6
  import { agentProtectedConfigViolation, captureAgentProtectedConfigSnapshot, changedAgentProtectedConfigPaths, } from "./agent-protected-config.js";
6
7
  import { agentGitStateViolation, captureAgentGitStateSnapshot, changedAgentGitStateFields, } from "./agent-git-state.js";
7
8
  import { ensureDir, safeSlug } from "./shared.js";
9
+ import { localConfigEnvironment } from "../shared/local-config.js";
8
10
  import { gitEnvironment, gitResult, worktreeNameFromTaskId } from "./worktree.js";
9
11
  import { getProjectSchedulePath, loadConfig, resolveAgentMember, specdojoRootDir, } from "../shared/specdojo-config.js";
10
12
  export const TRIAL_PROMPT_SUFFIX = `
@@ -179,11 +181,12 @@ export function resolveMember(roster, nickname, stageRole) {
179
181
  }
180
182
  return member;
181
183
  }
182
- export function spawnAgent(command, prompt, cwd, env) {
184
+ export function spawnAgent(command, prompt, cwd, env, stageRole = "executor") {
183
185
  return new Promise((resolveOutcome) => {
184
186
  const protectedConfigBefore = captureAgentProtectedConfigSnapshot(cwd);
185
187
  const gitStateBefore = captureAgentGitStateSnapshot(cwd);
186
188
  const child = spawn(command, { cwd, env, shell: true, stdio: ["pipe", "pipe", "pipe"] });
189
+ const stopTracking = stageRole === "executor" ? trackExecutor(child.pid, cwd) : () => undefined;
187
190
  let stdout = "";
188
191
  let stderr = "";
189
192
  let settled = false;
@@ -202,6 +205,7 @@ export function spawnAgent(command, prompt, cwd, env) {
202
205
  if (settled)
203
206
  return;
204
207
  settled = true;
208
+ stopTracking();
205
209
  const protectedChanges = changedAgentProtectedConfigPaths(cwd, protectedConfigBefore);
206
210
  if (protectedChanges.length > 0) {
207
211
  outcome.stderr += `${agentProtectedConfigViolation(protectedChanges)}\n`;
@@ -225,6 +229,7 @@ export function spawnAgent(command, prompt, cwd, env) {
225
229
  export function worktreeEnvironment(repoRoot, worktreePath, schedulePath, executionPath) {
226
230
  return {
227
231
  ...gitEnvironment(),
232
+ ...localConfigEnvironment(repoRoot),
228
233
  SPECDOJO_SCHEDULE_PATH: resolve(worktreePath, repoRelative(repoRoot, schedulePath)),
229
234
  SPECDOJO_EXECUTION_PATH: resolve(worktreePath, repoRelative(repoRoot, executionPath)),
230
235
  };
@@ -0,0 +1,181 @@
1
+ import { AsyncLocalStorage } from "node:async_hooks";
2
+ import { randomUUID } from "node:crypto";
3
+ import { appendFileSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
4
+ import { basename, dirname, join } from "node:path";
5
+ import { performance } from "node:perf_hooks";
6
+ import { getActiveExecLocksDir, isLiveLock, livePoolHolders, readLockOwner } from "./slot-lock.js";
7
+ import { redactSensitiveText } from "./evidence.js";
8
+ // Diagnostics are observational: inaccessible /proc, locks, or output must never fail a run.
9
+ function optional(read) {
10
+ try {
11
+ return read();
12
+ }
13
+ catch {
14
+ return undefined;
15
+ }
16
+ }
17
+ export function collectValidationLoad(procRoot = "/proc") {
18
+ const pressure = Object.fromEntries(["cpu", "memory", "io"].flatMap((resource) => {
19
+ const value = optional(() => readFileSync(join(procRoot, "pressure", resource), "utf8").trim());
20
+ return value === undefined ? [] : [[resource, value]];
21
+ }));
22
+ const memory = optional(() => {
23
+ const text = readFileSync(join(procRoot, "meminfo"), "utf8");
24
+ const fields = Object.fromEntries([...text.matchAll(/^(\w+):\s+(\d+) kB$/gm)].map((match) => [
25
+ match[1],
26
+ Number(match[2]) * 1024,
27
+ ]));
28
+ if (![fields.MemTotal, fields.MemAvailable, fields.SwapTotal, fields.SwapFree].every(Number.isFinite))
29
+ return undefined;
30
+ return {
31
+ total_bytes: fields.MemTotal,
32
+ available_bytes: fields.MemAvailable,
33
+ used_bytes: fields.MemTotal - fields.MemAvailable,
34
+ swap_total_bytes: fields.SwapTotal,
35
+ swap_used_bytes: fields.SwapTotal - fields.SwapFree,
36
+ };
37
+ });
38
+ const loadavg = optional(() => readFileSync(join(procRoot, "loadavg"), "utf8").trim());
39
+ return {
40
+ ...(Object.keys(pressure).length ? { pressure } : {}),
41
+ ...(memory ? { memory } : {}),
42
+ ...(loadavg ? { loadavg } : {}),
43
+ };
44
+ }
45
+ const localExecutors = new Map();
46
+ /** Called only while an executor child is alive; no command, prompt, or environment is stored. */
47
+ export function trackExecutor(pid, cwd) {
48
+ if (!pid)
49
+ return () => undefined;
50
+ const key = `${process.pid}-${pid}-${randomUUID()}`;
51
+ const activity = { pid, runner_pid: process.pid, worktree: basename(cwd) };
52
+ localExecutors.set(key, activity);
53
+ const root = getActiveExecLocksDir();
54
+ const file = root ? join(root, "metrics-executors", `${key}.json`) : undefined;
55
+ if (file)
56
+ optional(() => {
57
+ mkdirSync(dirname(file), { recursive: true });
58
+ writeFileSync(file, JSON.stringify(activity));
59
+ });
60
+ return () => {
61
+ localExecutors.delete(key);
62
+ if (file)
63
+ optional(() => unlinkSync(file));
64
+ };
65
+ }
66
+ function alive(pid) {
67
+ try {
68
+ process.kill(pid, 0);
69
+ return true;
70
+ }
71
+ catch (error) {
72
+ return error.code === "EPERM";
73
+ }
74
+ }
75
+ export function collectValidationActivity(lockRoot = getActiveExecLocksDir()) {
76
+ const executors = new Map(localExecutors);
77
+ const runs = [];
78
+ if (lockRoot) {
79
+ optional(() => {
80
+ const primary = join(lockRoot, "exec-run.lock");
81
+ const owner = isLiveLock(primary) ? readLockOwner(primary) : null;
82
+ if (owner)
83
+ runs.push({ pid: owner.pid, actor: owner.actor });
84
+ for (const slot of livePoolHolders(join(lockRoot, "exec-run-join"))) {
85
+ if (slot.owner)
86
+ runs.push({ pid: slot.owner.pid, actor: slot.owner.actor });
87
+ }
88
+ });
89
+ const directory = join(lockRoot, "metrics-executors");
90
+ for (const name of optional(() => readdirSync(directory)) ?? []) {
91
+ if (!name.endsWith(".json"))
92
+ continue;
93
+ optional(() => {
94
+ const value = JSON.parse(readFileSync(join(directory, name), "utf8"));
95
+ if (Number.isSafeInteger(value.pid) &&
96
+ value.pid > 0 &&
97
+ Number.isSafeInteger(value.runner_pid) &&
98
+ value.runner_pid > 0 &&
99
+ typeof value.worktree === "string" &&
100
+ alive(value.pid) &&
101
+ alive(value.runner_pid))
102
+ executors.set(name.slice(0, -5), value);
103
+ });
104
+ }
105
+ }
106
+ return {
107
+ scope: lockRoot ? "project-locks" : "process",
108
+ run_count: lockRoot ? runs.length : 1,
109
+ runs: lockRoot ? runs : [{ pid: process.pid }],
110
+ executor_count: executors.size,
111
+ executors: [...executors.values()],
112
+ };
113
+ }
114
+ const contexts = new AsyncLocalStorage();
115
+ export function withValidationMetrics(label, path, task) {
116
+ return contexts.run({ batch: randomUUID(), label, path, gateWaitMs: 0 }, task);
117
+ }
118
+ export function validationMetric(event, fields = {}) {
119
+ const context = contexts.getStore();
120
+ if (!context)
121
+ return;
122
+ optional(() => {
123
+ const line = redactSensitiveText(JSON.stringify({
124
+ schema_version: 1,
125
+ batch_id: context.batch,
126
+ label: context.label,
127
+ runner_pid: process.pid,
128
+ event,
129
+ at: new Date().toISOString(),
130
+ gate_wait_ms: context.gateWaitMs,
131
+ ...fields,
132
+ load: collectValidationLoad(),
133
+ activity: collectValidationActivity(),
134
+ })) + "\n";
135
+ if (context.path) {
136
+ mkdirSync(dirname(context.path), { recursive: true });
137
+ appendFileSync(context.path, line);
138
+ }
139
+ else
140
+ process.stdout.write(` Parent validation metrics: ${line}`);
141
+ });
142
+ }
143
+ export function recordValidationGateWait(start, localWaitMs) {
144
+ const context = contexts.getStore();
145
+ const total = performance.now() - start;
146
+ if (context)
147
+ context.gateWaitMs = total;
148
+ validationMetric("gate-acquired", {
149
+ local_wait_ms: localWaitMs,
150
+ shared_wait_ms: Math.max(0, total - localWaitMs),
151
+ });
152
+ }
153
+ export const TEST_FILE_METRIC_PREFIX = "[parent-validation:test-file] ";
154
+ /** Bounded stream parser; active files come from notifications, never guessed from completed tests. */
155
+ export class ValidationTestFiles {
156
+ pending = "";
157
+ active = new Set();
158
+ tail = "";
159
+ observe(chunk) {
160
+ this.tail = (this.tail + chunk).slice(-16_384);
161
+ const lines = (this.pending + chunk).split("\n");
162
+ this.pending = (lines.pop() ?? "").slice(-16_384);
163
+ for (const line of lines) {
164
+ const index = line.indexOf(TEST_FILE_METRIC_PREFIX);
165
+ if (index < 0)
166
+ continue;
167
+ optional(() => {
168
+ const value = JSON.parse(line.slice(index + TEST_FILE_METRIC_PREFIX.length));
169
+ if (typeof value.file !== "string" || value.file.length > 4096)
170
+ return;
171
+ if (value.event === "start" && this.active.size < 256)
172
+ this.active.add(value.file);
173
+ if (value.event === "end")
174
+ this.active.delete(value.file);
175
+ });
176
+ }
177
+ }
178
+ snapshot() {
179
+ return { active_test_files: [...this.active], output_tail: redactSensitiveText(this.tail) };
180
+ }
181
+ }
@@ -0,0 +1,26 @@
1
+ import { join } from "node:path";
2
+ import { ensureDir } from "../shared/fs.js";
3
+ import { isLiveLock, releaseLock, tryAcquireLock } from "./slot-lock.js";
4
+ import { worktreeNameFromTaskId } from "./worktree.js";
5
+ // PJR-NHT7: 統合の後の片付けは exec-lifecycle のロックの外で行う。その間に同じ項目の再実行・
6
+ // 再開・`exec worktree remove` が同じ worktree を消し始めないよう、worktree ごとのロックを取る。
7
+ // ロックは heartbeat を持つため、片付けの途中でプロセスが落ちても古くなれば次の操作が引き継ぐ。
8
+ export function worktreeCleanupLockDir(executionPath, worktreeTaskId) {
9
+ return join(executionPath, "exec", ".locks", "worktree-cleanup", worktreeNameFromTaskId(worktreeTaskId));
10
+ }
11
+ export function isWorktreeCleanupInProgress(executionPath, worktreeTaskId) {
12
+ return isLiveLock(worktreeCleanupLockDir(executionPath, worktreeTaskId));
13
+ }
14
+ export function worktreeCleanupInProgressReason(worktreeTaskId) {
15
+ return (`the worktree of ${worktreeTaskId} is still being removed after its integration; ` +
16
+ `retry after the cleanup finishes`);
17
+ }
18
+ // 取れなかった場合(別の片付けが進行中)は null を返す。呼び出し側は片付けを始めない。
19
+ export function tryAcquireWorktreeCleanupLock(executionPath, worktreeTaskId, actor) {
20
+ const lockDir = worktreeCleanupLockDir(executionPath, worktreeTaskId);
21
+ ensureDir(join(lockDir, ".."));
22
+ return tryAcquireLock(lockDir, { actor, label: `worktree cleanup ${worktreeTaskId}` });
23
+ }
24
+ export function releaseWorktreeCleanupLock(handle) {
25
+ releaseLock(handle);
26
+ }
@@ -15,11 +15,13 @@ import { buildTaskPhaseMap, loadPrompt, loadRosterForExecutionPath, resolveTaskP
15
15
  import { buildInitialStateFromStrategy } from "./schedule/initial.js";
16
16
  import { buildScheduleIndex } from "./schedule/schedule.js";
17
17
  import { qualifyTaskId } from "./shared.js";
18
+ import { localConfigEnvironment } from "../shared/local-config.js";
18
19
  import { configuredProductRepos, missingProductWorktrees, plannedProjectWorktreePath, productBranchForTask, productRepoEnvironment, pruneOrphanedProductExecBranches, withAgentExtraRoots, withoutInheritedRepoEnvironment, withProductRepoPrompt, withProductWorktrees, } from "./task-repos.js";
19
20
  import { buildTaskView } from "./task-view.js";
20
21
  import { checkpointAndEnsureWorktree, commitWorktreeChanges, mergeWorktreeIntoCurrent, pruneOrphanedExecBranches, removeWorktree, taskPaths, worktreeStatusPaths, } from "./worktree-ops.js";
21
22
  import { branchOwnedRunRecordPaths } from "./trailing-records.js";
22
23
  import { findExecWorktree, gitEnvironment, gitOutput, gitResult, resolveWorktreeBase, worktreeNameFromTaskId, } from "./worktree.js";
24
+ import { isWorktreeCleanupInProgress, worktreeCleanupInProgressReason, } from "./worktree-cleanup-lock.js";
23
25
  export { isCommitTargetPath, stabilizeCommitTargets } from "./worktree-ops.js";
24
26
  const DEFAULT_LOCK_TIMEOUT_MS = 10_000;
25
27
  const DEFAULT_LOCK_STALE_MS = 300_000;
@@ -277,6 +279,7 @@ async function agent(opts) {
277
279
  cwd: worktree.path,
278
280
  env: {
279
281
  ...withoutInheritedRepoEnvironment(gitEnvironment()),
282
+ ...localConfigEnvironment(worktree.path),
280
283
  SPECDOJO_SCHEDULE_PATH: context.schedulePath,
281
284
  SPECDOJO_EXECUTION_PATH: context.executionPath,
282
285
  ...productRepoEnvironment(worktree.path, worktree.repos),
@@ -364,7 +367,12 @@ function merge(opts) {
364
367
  }
365
368
  function remove(opts) {
366
369
  const context = resolveContext(opts);
367
- const worktree = requireWorktree(context, qualifyTaskId(context.projectId, opts.task));
370
+ const worktreeTaskId = qualifyTaskId(context.projectId, opts.task);
371
+ // runner が統合の後の撤去をロックの外で進めている間は、同じ worktree を二重に消さない。
372
+ if (isWorktreeCleanupInProgress(context.executionPath, worktreeTaskId)) {
373
+ throw new Error(worktreeCleanupInProgressReason(worktreeTaskId));
374
+ }
375
+ const worktree = requireWorktree(context, worktreeTaskId);
368
376
  removeWorktree({
369
377
  context,
370
378
  worktree,
@@ -421,8 +421,8 @@ export function commitTargetPaths(context, worktree, taskId, options = {}) {
421
421
  export class UncommittedChangesError extends Error {
422
422
  files;
423
423
  constructor(files, logPath) {
424
- const sample = files.slice(0, 3).join(", ");
425
- super(`uncommitted=${files.length}; log=${logPath}; files=${sample}${files.length > 3 ? ", …" : ""}`);
424
+ // This message becomes the result's block_reason; retain every excluded path.
425
+ super(`uncommitted=${files.length}; log=${logPath}; files=${files.join(", ")}`);
426
426
  this.files = files;
427
427
  this.name = "UncommittedChangesError";
428
428
  }
@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
2
2
  import { existsSync, lstatSync, mkdirSync, rmSync, unlinkSync } from "node:fs";
3
3
  import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
4
4
  import { describeGitProcessFailure, formatGitCommandFailure, GitCommandError, gitEnvironment, gitOutput, gitResult, } from "../shared/git.js";
5
+ import { localConfigEnvironment } from "../shared/local-config.js";
5
6
  export { appendGitFailureLog, appendGitResultFailureLog, describeGitProcessFailure, formatGitCommandFailure, formatGitResultFailure, GIT_LOCAL_ENV_VARS, GIT_OUTPUT_MAX_BUFFER, GitCommandError, gitEnvironment, gitOutput, gitResult, isGitDubiousOwnership, isGitIndexLockContention, isGitNotRepositoryWithGitMetadata, runGitWithTransientRetry, summarizeGitArguments, summarizeGitHookFailure, summarizeGitStderr, transientGitFailureReason, } from "../shared/git.js";
6
7
  export function worktreeNameFromTaskId(value) {
7
8
  const slug = value
@@ -145,6 +146,15 @@ export function formatWorktreeBuildFailure(worktreePath, detail) {
145
146
  `Generated docs are gitignored and must be rebuilt per worktree, so this is a ` +
146
147
  `preparation failure, not a task deliverable failure.`);
147
148
  }
149
+ /** Environment of `specdojo build` in a worktree, including the main tree's local config. */
150
+ export function worktreeBuildEnvironment(worktreePath) {
151
+ return {
152
+ ...gitEnvironment(),
153
+ ...localConfigEnvironment(worktreePath),
154
+ CI: "true",
155
+ LEFTHOOK: "0",
156
+ };
157
+ }
148
158
  // build は worktree 内で完結させる。依存と同じく、worktree の checkout にある CLI を使うため、
149
159
  // 実行元プロセスの entry(テストランナー等)へは依存しない。SpecDojo 自身のリポジトリでは
150
160
  // src の entry を worktree の tsx で、CLI を依存として使うリポジトリでは
@@ -165,7 +175,8 @@ export function resolveWorktreeBuildCommand(worktreePath) {
165
175
  return null;
166
176
  }
167
177
  // worktree を cwd にして build を実行する。child は cwd から .specdojo/specdojo.config.json を
168
- // 辿るため、生成先は worktree 側になる。
178
+ // 辿るため、生成先は worktree 側になる。ローカル設定は worktree へ複製せず、主の作業ツリーの
179
+ // ファイルのパスを環境変数で渡す(PJR-NC9R)。
169
180
  function runWorktreeBuild(worktreePath) {
170
181
  const resolved = resolveWorktreeBuildCommand(worktreePath);
171
182
  if (!resolved) {
@@ -175,7 +186,7 @@ function runWorktreeBuild(worktreePath) {
175
186
  process.stdout.write("Generating worktree artifacts: specdojo build\n");
176
187
  const result = spawnSync(resolved.command, resolved.args, {
177
188
  cwd: worktreePath,
178
- env: { ...gitEnvironment(), CI: "true", LEFTHOOK: "0" },
189
+ env: worktreeBuildEnvironment(worktreePath),
179
190
  stdio: "inherit",
180
191
  });
181
192
  if (result.error) {
@@ -22,7 +22,7 @@ export function renderGradeFindingTranslationPlan(result, translationIndex) {
22
22
  }
23
23
  export function registerGradeApplyCommands(grade) {
24
24
  addSelection(grade
25
- .command("apply")
25
+ .command("apply", { hidden: true })
26
26
  .description("Convert executor markers (or validate reporter JSON), calculate scores, and update documents"))
27
27
  .option("--from <path>", "GradeSubmission JSON produced by an LLM reporter; omit to convert --analysis-from mechanically")
28
28
  .requiredOption("--by <nickname>", "Grading agent nickname from agent-members.yaml")
@@ -144,7 +144,7 @@ export function registerGradeApplyCommands(grade) {
144
144
  }
145
145
  });
146
146
  addSelection(grade
147
- .command("translation-plan")
147
+ .command("translation-plan", { hidden: true })
148
148
  .description("Create a Japanese translation request for the latest canonical findings"))
149
149
  .requiredOption("--out <path>", "Write the translation plan to this repository path")
150
150
  .option("--translation-index <index>", "Translate only this zero-based index from the translatable findings", requireNonNegativeInteger)
@@ -189,7 +189,7 @@ export function registerGradeApplyCommands(grade) {
189
189
  }
190
190
  });
191
191
  addSelection(grade
192
- .command("localize")
192
+ .command("localize", { hidden: true })
193
193
  .description("Attach Japanese display messages to the latest canonical grade findings"))
194
194
  .requiredOption("--from <path>", "JSON string array returned by the translation agent")
195
195
  .option("--translation-index <index>", "Apply a retry for this zero-based index from the translatable findings", requireNonNegativeInteger)
@@ -6,7 +6,9 @@ import { readGradeResultForDocument } from "./result.js";
6
6
  import { repoRelativePath, resolveSafeMarkdownPath } from "./targets.js";
7
7
  import { specdojoRootDir } from "../shared/specdojo-config.js";
8
8
  export function registerGradeInspectionCommands(grade) {
9
- addSelection(grade.command("validate").description("Validate stored grade hashes and finding counts")).action((options) => {
9
+ addSelection(grade
10
+ .command("validate", { hidden: true })
11
+ .description("Validate stored grade hashes and finding counts")).action((options) => {
10
12
  try {
11
13
  const target = requireTarget(options.target);
12
14
  const paths = discoverGradeTargets({
@@ -36,7 +38,7 @@ export function registerGradeInspectionCommands(grade) {
36
38
  }
37
39
  });
38
40
  grade
39
- .command("result")
41
+ .command("result", { hidden: true })
40
42
  .description("Print the stored grade result sidecar for one document as JSON")
41
43
  .requiredOption("--path <path>", "Markdown or YAML document whose grade result is read")
42
44
  .option("--project <projectId>", "Project id in specdojo.config.json")
@@ -53,7 +55,7 @@ export function registerGradeInspectionCommands(grade) {
53
55
  }
54
56
  });
55
57
  grade
56
- .command("state")
58
+ .command("state", { hidden: true })
57
59
  .description("Read or update persistent per-document grade pipeline state")
58
60
  .requiredOption("--target <target>", "kata or deliverable")
59
61
  .option("--project <projectId>", "Project id in specdojo.config.json")
@@ -30,7 +30,7 @@ export function registerGradePlanCommands(grade) {
30
30
  }
31
31
  });
32
32
  addSelection(grade
33
- .command("plan")
33
+ .command("plan", { hidden: true })
34
34
  .description("Write reusable executor and reporter plans per selected document"))
35
35
  .option("--out <directory>", "Write plans below this repository-relative directory")
36
36
  .option("--reference <path>", "Use this document as the comparison reference")
@@ -1,5 +1,5 @@
1
1
  import { addGradeSelectionOptions, commandError, requirePositiveInteger, requireTarget, } from "./command-shared.js";
2
- import { runGrade } from "./run.js";
2
+ import { GradeRunIncompleteError, runGrade } from "./run.js";
3
3
  export function registerGradeRunCommand(grade, runtime) {
4
4
  addGradeSelectionOptions(grade
5
5
  .command("run")
@@ -13,6 +13,7 @@ export function registerGradeRunCommand(grade, runtime) {
13
13
  .option("--isolate-pipeline-state", "Keep retry state inside this run directory")
14
14
  .option("--if-busy <policy>", "Project grade lock policy: fail or wait")
15
15
  .option("--reference <path>", "Comparison reference document")
16
+ .option("--reference-per-kind", "Kata only: compare each document with the same-kind prj-overview document", false)
16
17
  .option("--embed-documents", "Embed target and reference contents", false)
17
18
  .option("--max-stage-failures <count>", "Consecutive failure limit", requirePositiveInteger, 3)
18
19
  .option("--limit <count>", "Maximum number of documents", requirePositiveInteger)
@@ -36,6 +37,9 @@ export function registerGradeRunCommand(grade, runtime) {
36
37
  }
37
38
  catch (error) {
38
39
  commandError(error);
40
+ // Exit 2 marks a partial run and 75 a rate limit; scheduled jobs tell them apart.
41
+ if (error instanceof GradeRunIncompleteError)
42
+ process.exitCode = error.exitCode;
39
43
  }
40
44
  });
41
45
  }
package/dist/grade/run.js CHANGED
@@ -6,9 +6,40 @@ import { delay, LOCK_POLL_MS, tryAcquireLock, releaseLock } from "../shared/cros
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
@@ -62,6 +93,10 @@ async function runGradeUnlocked(opts, runtime) {
62
93
  throw new Error("Invalid --max-stage-failures");
63
94
  if (opts.limit !== undefined && (!Number.isSafeInteger(opts.limit) || opts.limit < 1))
64
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");
65
100
  const { id: projectId, project } = resolveProject(opts.project);
66
101
  const viewpoints = loadViewpoints(projectId);
67
102
  const executionPath = getProjectExecutionPath(project);
@@ -119,12 +154,16 @@ async function runGradeUnlocked(opts, runtime) {
119
154
  const criteria = opts.target === "deliverable"
120
155
  ? resolveDeliverableDoneCriteria(state.documents.map((document) => document.path), projectId)
121
156
  : undefined;
157
+ const references = new Map(state.documents.map((document) => [
158
+ document.path,
159
+ opts.referencePerKind ? perKindReference(document.path) : opts.reference,
160
+ ]));
122
161
  // Validate all subjects before starting any agent or writing run files.
123
162
  for (const document of state.documents) {
124
163
  const path = resolveSafeMarkdownPath(document.path, specdojoRootDir(), projectId);
125
164
  const fingerprint = digest({
126
165
  content: gradeContentHash(readFileSync(path, "utf8")),
127
- reference: referenceHash(opts.reference, projectId),
166
+ reference: referenceHash(references.get(document.path), projectId),
128
167
  viewpoints,
129
168
  criteria: criteria?.get(document.path),
130
169
  sources: resolveGradeSourceHashes({
@@ -173,6 +212,7 @@ async function runGradeUnlocked(opts, runtime) {
173
212
  writeState(statePath, state);
174
213
  const failures = [];
175
214
  for (const [index, document] of state.documents.entries()) {
215
+ const reference = references.get(document.path);
176
216
  if (document.status === "complete") {
177
217
  recordGradePipelineStage({
178
218
  directory: pipelineStateDirectory,
@@ -217,7 +257,7 @@ async function runGradeUnlocked(opts, runtime) {
217
257
  target: opts.target,
218
258
  paths: [document.path],
219
259
  referenceExampleCandidates: [],
220
- referenceExampleOverride: opts.reference,
260
+ referenceExampleOverride: reference,
221
261
  viewpoints,
222
262
  projectId,
223
263
  outputDirectory: stageDirectory,
@@ -238,6 +278,18 @@ async function runGradeUnlocked(opts, runtime) {
238
278
  document.actor = actualActor;
239
279
  if (!execution)
240
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
+ }
241
293
  writeFileSync(join(stageDirectory, "executor-output.txt"), execution.stdout, "utf8");
242
294
  if (execution.result !== "success")
243
295
  throw new Error(`agent ${actualActor}: ${execution.result} exit=${execution.exitCode ?? "null"}`);
@@ -245,7 +297,7 @@ async function runGradeUnlocked(opts, runtime) {
245
297
  const currentPath = resolveSafeMarkdownPath(document.path, specdojoRootDir(), projectId);
246
298
  const currentFingerprint = digest({
247
299
  content: gradeContentHash(readFileSync(currentPath, "utf8")),
248
- reference: referenceHash(opts.reference, projectId),
300
+ reference: referenceHash(reference, projectId),
249
301
  viewpoints: loadViewpoints(projectId),
250
302
  criteria: opts.target === "deliverable"
251
303
  ? resolveDeliverableDoneCriteria([document.path], projectId).get(document.path)
@@ -274,7 +326,7 @@ async function runGradeUnlocked(opts, runtime) {
274
326
  viewpoints,
275
327
  target: opts.target,
276
328
  gradedBy: actualActor,
277
- reference: opts.reference,
329
+ reference,
278
330
  doneCriteriaByPath: criteria,
279
331
  criteriaDirectory: join(executionPath, "grade", "criteria"),
280
332
  resultsDirectory: join(executionPath, "grade", "results"),
@@ -301,9 +353,11 @@ async function runGradeUnlocked(opts, runtime) {
301
353
  maxFailures,
302
354
  status: "complete",
303
355
  });
304
- 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`);
305
357
  }
306
358
  catch (error) {
359
+ if (error instanceof GradeRunIncompleteError)
360
+ throw error;
307
361
  document.status = "failed";
308
362
  document.error = error instanceof Error ? error.message : String(error);
309
363
  writeState(statePath, state);
@@ -321,7 +375,9 @@ async function runGradeUnlocked(opts, runtime) {
321
375
  failures.push(`${document.path}: ${document.error}`);
322
376
  }
323
377
  }
324
- if (failures.length)
325
- 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
+ }
326
382
  return { documents: state.documents };
327
383
  }