specdojo 0.3.0 → 0.4.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 (245) hide show
  1. package/CHANGELOG.md +65 -0
  2. package/README.md +77 -18
  3. package/dist/catalog/build-references.js +144 -0
  4. package/dist/catalog/build-render.js +32 -0
  5. package/dist/{catalog-build.js → catalog/build.js} +18 -295
  6. package/dist/{catalog.js → catalog/catalog.js} +11 -11
  7. package/dist/{catalog-generate.js → catalog/generate.js} +13 -16
  8. package/dist/catalog/paths.js +1 -0
  9. package/dist/{catalog-plan-generate.js → catalog/plan-generate.js} +5 -5
  10. package/dist/{catalog-plan.js → catalog/plan.js} +9 -9
  11. package/dist/{catalog-scaffold.js → catalog/scaffold.js} +6 -6
  12. package/dist/{agent.js → commands/agent.js} +11 -11
  13. package/dist/{build-command.js → commands/build.js} +2 -2
  14. package/dist/{init-command.js → commands/init.js} +103 -37
  15. package/dist/{orchestrator.js → commands/orchestrator.js} +2 -2
  16. package/dist/{watch.js → commands/watch.js} +3 -3
  17. package/dist/dashboard/dashboard-timeline.js +175 -0
  18. package/dist/{dashboard.js → dashboard/dashboard.js} +16 -549
  19. package/dist/dashboard/exec-records.js +105 -0
  20. package/dist/dashboard/routines.js +256 -0
  21. package/dist/dashboard/shared.js +14 -0
  22. package/dist/{timeline-build.js → dashboard/timeline-build.js} +2 -1
  23. package/dist/{timeline.js → dashboard/timeline.js} +1 -1
  24. package/dist/{deliverable.js → deliverable/deliverable.js} +5 -5
  25. package/dist/{deliverable-trash.js → deliverable/trash.js} +7 -7
  26. package/dist/{devcontainer-command.js → devcontainer/command.js} +5 -3
  27. package/dist/{devcontainer-scaffold.js → devcontainer/scaffold.js} +94 -2
  28. package/dist/{doc-index.js → docs/doc-index.js} +3 -3
  29. package/dist/{frontmatter-namespace.js → docs/frontmatter-namespace.js} +2 -2
  30. package/dist/{index-command.js → docs/index-command.js} +1 -1
  31. package/dist/docs/template-resolution.js +1 -0
  32. package/dist/{viewpoint-document-kinds-check.js → docs/viewpoint-document-kinds-check.js} +3 -3
  33. package/dist/{yaml-pages-command.js → docs/yaml-pages-command.js} +1 -1
  34. package/dist/{yaml-pages.js → docs/yaml-pages.js} +5 -5
  35. package/dist/{exec-agent-config.js → exec/agent-config.js} +33 -4
  36. package/dist/{exec-agent-git-state.js → exec/agent-git-state.js} +1 -1
  37. package/dist/{exec-agent-protected-config.js → exec/agent-protected-config.js} +1 -1
  38. package/dist/{exec.js → exec/commands.js} +22 -467
  39. package/dist/exec/core.js +457 -0
  40. package/dist/{exec-events.js → exec/events.js} +2 -2
  41. package/dist/{exec-evidence.js → exec/evidence.js} +11 -6
  42. package/dist/exec/exec.js +2 -0
  43. package/dist/exec/format.js +1 -0
  44. package/dist/{exec-handoff.js → exec/handoff.js} +13 -12
  45. package/dist/{exec-limit.js → exec/limit.js} +93 -12
  46. package/dist/{exec-parent-validation.js → exec/parent-validation.js} +4 -4
  47. package/dist/{exec-pipeline-state.js → exec/pipeline-state.js} +16 -2
  48. package/dist/{exec-plans.js → exec/plans-core.js} +97 -468
  49. package/dist/exec/plans-generation.js +249 -0
  50. package/dist/exec/plans-storage.js +131 -0
  51. package/dist/exec/plans.js +3 -0
  52. package/dist/{exec-project.js → exec/project.js} +1 -1
  53. package/dist/{exec-protection-handoff.js → exec/protection-handoff.js} +3 -3
  54. package/dist/{exec-register-resume.js → exec/register-resume.js} +2 -2
  55. package/dist/{exec-register.js → exec/register.js} +92 -9
  56. package/dist/exec/repo-integration-git.js +23 -0
  57. package/dist/exec/repo-integration-sync.js +264 -0
  58. package/dist/{exec-repo-integration.js → exec/repo-integration.js} +13 -287
  59. package/dist/{exec-repo-trace.js → exec/repo-trace.js} +3 -3
  60. package/dist/exec/reporter-output.js +206 -0
  61. package/dist/{exec-reporter.js → exec/reporter.js} +29 -216
  62. package/dist/{exec-results.js → exec/results.js} +277 -36
  63. package/dist/exec/run/agent-pipeline.js +276 -0
  64. package/dist/exec/run/agent.js +583 -0
  65. package/dist/exec/run/in-place.js +570 -0
  66. package/dist/exec/run/job.js +746 -0
  67. package/dist/exec/run/lifecycle-commands.js +530 -0
  68. package/dist/{exec-run-lock.js → exec/run/lock.js} +4 -3
  69. package/dist/exec/run/mode-shared.js +140 -0
  70. package/dist/exec/run/register-command.js +252 -0
  71. package/dist/exec/run/register-core.js +411 -0
  72. package/dist/exec/run/register-mode.js +210 -0
  73. package/dist/exec/run/register-resume.js +398 -0
  74. package/dist/exec/run/register-state.js +325 -0
  75. package/dist/exec/run/register-worktree.js +540 -0
  76. package/dist/exec/run/run.js +11 -0
  77. package/dist/exec/run/schedule-mode.js +294 -0
  78. package/dist/exec/run/schedule-prepare.js +366 -0
  79. package/dist/exec/run/schedule-task.js +599 -0
  80. package/dist/exec/run/shared.js +449 -0
  81. package/dist/{exec-schedule-calendar.js → exec/schedule/calendar.js} +1 -1
  82. package/dist/{exec-schedule-cpm.js → exec/schedule/cpm.js} +2 -2
  83. package/dist/{exec-schedule-gantt-chart-render.js → exec/schedule/gantt-chart-render.js} +2 -2
  84. package/dist/exec/schedule/gantt-chart.js +2 -0
  85. package/dist/{exec-schedule-hash.js → exec/schedule/hash.js} +2 -2
  86. package/dist/exec/schedule/index.js +1 -0
  87. package/dist/{exec-schedule-initial.js → exec/schedule/initial.js} +2 -2
  88. package/dist/{exec-schedule-progress.js → exec/schedule/progress.js} +2 -2
  89. package/dist/{exec-schedule-ready.js → exec/schedule/ready.js} +2 -2
  90. package/dist/{exec-schedule.js → exec/schedule/schedule.js} +11 -11
  91. package/dist/exec/shared.js +63 -0
  92. package/dist/exec/slot-lock.js +1 -0
  93. package/dist/{exec-strategy.js → exec/strategy.js} +2 -2
  94. package/dist/{exec-task-repos.js → exec/task-repos.js} +2 -2
  95. package/dist/{exec-task-view.js → exec/task-view.js} +4 -4
  96. package/dist/{exec-trial.js → exec/trial-commands.js} +23 -388
  97. package/dist/exec/trial-core.js +371 -0
  98. package/dist/exec/trial.js +2 -0
  99. package/dist/{exec-worktree-command.js → exec/worktree-command.js} +25 -23
  100. package/dist/exec/worktree-ops-commit.js +672 -0
  101. package/dist/exec/worktree-ops-lifecycle.js +297 -0
  102. package/dist/exec/worktree-ops-merge.js +344 -0
  103. package/dist/exec/worktree-ops.js +3 -0
  104. package/dist/exec/worktree.js +305 -0
  105. package/dist/grade/apply.js +734 -0
  106. package/dist/grade/command-apply.js +250 -0
  107. package/dist/grade/command-inspect.js +138 -0
  108. package/dist/grade/command-plan.js +101 -0
  109. package/dist/grade/command-shared.js +68 -0
  110. package/dist/grade/core.js +307 -0
  111. package/dist/grade/grade.js +19 -0
  112. package/dist/grade/markdown.js +274 -0
  113. package/dist/grade/pipeline-state.js +184 -0
  114. package/dist/grade/plan.js +507 -0
  115. package/dist/{grade-result.js → grade/result.js} +7 -96
  116. package/dist/grade/target-discovery.js +265 -0
  117. package/dist/grade/targets.js +435 -0
  118. package/dist/{job.js → job/definition.js} +32 -574
  119. package/dist/job/job.js +568 -0
  120. package/dist/{kata-command.js → kata/command.js} +4 -4
  121. package/dist/{kata.js → kata/kata.js} +5 -5
  122. package/dist/register/approach.js +134 -0
  123. package/dist/register/command-types.js +1 -0
  124. package/dist/register/core.js +369 -0
  125. package/dist/register/create-commands.js +352 -0
  126. package/dist/{register-date.js → register/date.js} +1 -1
  127. package/dist/register/derivation.js +163 -0
  128. package/dist/{register-event-merge.js → register/event-merge.js} +32 -3
  129. package/dist/{register-events.js → register/events.js} +12 -6
  130. package/dist/{register-history.js → register/history.js} +7 -6
  131. package/dist/{register-item.js → register/item.js} +28 -10
  132. package/dist/register/lifecycle-lock.js +5 -0
  133. package/dist/register/maintenance-commands.js +193 -0
  134. package/dist/{register-migrate-timestamps.js → register/migrate-timestamps.js} +3 -3
  135. package/dist/register/migration.js +268 -0
  136. package/dist/register/register.js +404 -0
  137. package/dist/register/renumber.js +341 -0
  138. package/dist/register/transition-commands.js +248 -0
  139. package/dist/register/update.js +230 -0
  140. package/dist/register/views.js +296 -0
  141. package/dist/{review-grade.js → review/grade.js} +2 -2
  142. package/dist/{review-plan.js → review/plan.js} +5 -5
  143. package/dist/routine/definition.js +401 -0
  144. package/dist/{routine.js → routine/routine.js} +50 -419
  145. package/dist/{schedule-approach.js → schedule/approach.js} +9 -9
  146. package/dist/{schedule-build.js → schedule/build.js} +7 -4
  147. package/dist/{schedule.js → schedule/schedule.js} +9 -9
  148. package/dist/schedule/strategy-generate-document.js +273 -0
  149. package/dist/schedule/strategy-generate-scope.js +199 -0
  150. package/dist/schedule/strategy-generate.js +348 -0
  151. package/dist/shared/agent-types.js +23 -0
  152. package/dist/shared/artifact-path.js +9 -0
  153. package/dist/{build-if-stale.js → shared/build-if-stale.js} +1 -1
  154. package/dist/shared/catalog-render.js +115 -0
  155. package/dist/{exec-slot-lock.js → shared/cross-process-lock.js} +3 -1
  156. package/dist/shared/fs.js +30 -0
  157. package/dist/shared/git.js +316 -0
  158. package/dist/shared/grade-result.js +94 -0
  159. package/dist/{package-paths.js → shared/package-paths.js} +3 -3
  160. package/dist/shared/plan-templates.js +114 -0
  161. package/dist/{exec-provider-scaffold.js → shared/provider-scaffold.js} +3 -1
  162. package/dist/shared/random.js +4 -0
  163. package/dist/{exec-schedule-index.js → shared/schedule-index.js} +3 -1
  164. package/dist/shared/schedule-paths.js +9 -0
  165. package/dist/{specdojo-config.js → shared/specdojo-config.js} +96 -9
  166. package/dist/{exec-shared.js → shared/text.js} +0 -134
  167. package/dist/shared/time.js +28 -0
  168. package/dist/shared/yaml.js +28 -0
  169. package/dist/specdojo.js +22 -22
  170. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +29 -17
  171. package/docs/ja/specdojo/exec-templates/xep-register-investigate-template.md +1 -2
  172. package/docs/ja/specdojo/exec-templates/xep-register-template.md +1 -2
  173. package/docs/ja/specdojo/exec-templates/xer-template.md +1 -3
  174. package/docs/ja/specdojo/exec-templates/xrp-job-template.md +6 -4
  175. package/docs/ja/specdojo/guides/exec-config-guide.md +97 -22
  176. package/docs/ja/specdojo/guides/exec-operation-guide.md +145 -12
  177. package/docs/ja/specdojo/guides/exec-worktree-guide.md +2 -0
  178. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +51 -18
  179. package/docs/ja/specdojo/guides/quick-start-guide.md +81 -16
  180. package/docs/ja/specdojo/guides/register-operation-guide.md +2 -1
  181. package/docs/ja/specdojo/guides/remote-host-development-guide.md +10 -1
  182. package/docs/ja/specdojo/guides/review-guide.md +1 -1
  183. package/docs/ja/specdojo/guides/routine-operation-guide.md +6 -6
  184. package/docs/ja/specdojo/guides/use-case-guide.md +1 -1
  185. package/docs/ja/specdojo/references/command-reference.md +52 -28
  186. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +17 -11
  187. package/docs/ja/specdojo/standards/job-definition-standard.md +20 -18
  188. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +2 -2
  189. package/docs/ja/specdojo/templates/pjr-derived-items-template.md +22 -0
  190. package/docs/ja/specdojo/templates/pjr-index-template.md +1 -0
  191. package/docs/specdojo/schemas/v1/agent-members.schema.yaml +29 -2
  192. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +20 -0
  193. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +23 -0
  194. package/docs/specdojo/schemas/v1/job-run.schema.yaml +2 -2
  195. package/docs/specdojo/schemas/v1/job.schema.yaml +7 -0
  196. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +26 -0
  197. package/docs/specdojo/schemas/v1/register-events.schema.yaml +3 -0
  198. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +70 -7
  199. package/docs/specdojo/schemas/v1/routine-run.schema.yaml +1 -1
  200. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +1 -1
  201. package/package.json +4 -5
  202. package/templates/antigravity/README.md +7 -3
  203. package/templates/antigravity/agent-members-snippet.yaml +108 -12
  204. package/templates/antigravity/exec-defaults-snippet.yaml +10 -13
  205. package/templates/claude/README.md +27 -3
  206. package/templates/claude/agents/claude-executor.md +0 -1
  207. package/templates/claude/agents/claude-reporter.md +2 -1
  208. package/templates/claude/agents/claude-review-executor.md +0 -1
  209. package/templates/codex/README.md +23 -4
  210. package/templates/devcontainer/devcontainer.json +2 -2
  211. package/templates/devcontainer/remote-host/specdojo-tmux.sh.sample +69 -0
  212. package/templates/devcontainer/remote-host/ssh-config.sample +16 -0
  213. package/templates/init-agent-members.yaml +75 -25
  214. package/templates/init-exec-defaults.yaml +26 -8
  215. package/templates/opencode/README.md +17 -3
  216. package/templates/opencode/agents/opencode-executor.md +0 -1
  217. package/templates/opencode/agents/opencode-reporter.md +2 -1
  218. package/templates/opencode/agents/opencode-review-executor.md +0 -1
  219. package/dist/exec-run.js +0 -6182
  220. package/dist/exec-schedule-gantt-chart.js +0 -2
  221. package/dist/exec-worktree-ops.js +0 -1292
  222. package/dist/exec-worktree.js +0 -446
  223. package/dist/grade.js +0 -3193
  224. package/dist/register.js +0 -2407
  225. package/dist/schedule-strategy-generate.js +0 -812
  226. package/templates/claude/agents/claude-expert-review-executor.md +0 -14
  227. /package/dist/{catalog-plan-prompt.js → catalog/plan-prompt.js} +0 -0
  228. /package/dist/{catalog-types.js → catalog/types.js} +0 -0
  229. /package/dist/{template-frontmatter.js → docs/template-frontmatter.js} +0 -0
  230. /package/dist/{role-types.js → exec/role-types.js} +0 -0
  231. /package/dist/{exec-schedule-gantt-chart-scope.js → exec/schedule/gantt-chart-scope.js} +0 -0
  232. /package/dist/{exec-types.js → exec/types.js} +0 -0
  233. /package/dist/{review-types.js → review/types.js} +0 -0
  234. /package/dist/{schedule-phase-sets.js → schedule/phase-sets.js} +0 -0
  235. /package/dist/{schedule-strategy-profiles.js → schedule/strategy-profiles.js} +0 -0
  236. /package/dist/{agent-response.js → shared/agent-response.js} +0 -0
  237. /package/dist/{catalog-paths.js → shared/catalog-paths.js} +0 -0
  238. /package/dist/{dist-freshness.js → shared/dist-freshness.js} +0 -0
  239. /package/dist/{git-environment.js → shared/git-environment.js} +0 -0
  240. /package/dist/{exec-format.js → shared/markdown-format.js} +0 -0
  241. /package/dist/{practice-id.js → shared/practice-id.js} +0 -0
  242. /package/dist/{spawn-self.js → shared/spawn-self.js} +0 -0
  243. /package/dist/{specdojo-gitignore.js → shared/specdojo-gitignore.js} +0 -0
  244. /package/dist/{template-resolution.js → shared/template-resolution.js} +0 -0
  245. /package/dist/{yaml-schema-modeline.js → shared/yaml-schema-modeline.js} +0 -0
@@ -0,0 +1,140 @@
1
+ import { spawnSync } from "node:child_process";
2
+ import { existsSync } from "node:fs";
3
+ import { dirname, join, relative, sep } from "node:path";
4
+ import { selfRunArgs } from "../../shared/spawn-self.js";
5
+ import { specdojoRootDir } from "../../shared/specdojo-config.js";
6
+ import { readPipelineState, updatePipelineRepoIntegration, updatePipelineStage, writePipelineState, } from "../pipeline-state.js";
7
+ export function spawnSelf(args, cwd = specdojoRootDir()) {
8
+ const [exe, fullArgs] = selfRunArgs(args);
9
+ const result = spawnSync(exe, fullArgs, { stdio: "inherit", cwd });
10
+ return result.status === 0;
11
+ }
12
+ export function spawnValidate(projectId) {
13
+ const args = ["exec", "validate"];
14
+ if (projectId)
15
+ args.push("--project", projectId);
16
+ return spawnSelf(args);
17
+ }
18
+ export function spawnRefresh(projectId) {
19
+ const refreshArgs = ["exec", "refresh"];
20
+ if (projectId)
21
+ refreshArgs.push("--project", projectId);
22
+ return spawnSelf(refreshArgs);
23
+ }
24
+ export function spawnScheduleBuild(projectId, track) {
25
+ const args = ["schedule", "build", "--track", track, "--force"];
26
+ if (projectId)
27
+ args.push("--project", projectId);
28
+ return spawnSelf(args);
29
+ }
30
+ // doc-index is project-independent (it scans the whole docs/ tree), so no --project is passed.
31
+ // Rebuilding it before Ready selection lets tasks resolve wikilinks/IDs to deliverables that a
32
+ // prior round or a prior cycle step just created (see scheduleAvailable and runCycleMode).
33
+ export function spawnIndexBuild() {
34
+ return spawnSelf(["index", "build"]);
35
+ }
36
+ export function spawnClaim(projectId, taskId, by) {
37
+ const args = [
38
+ "exec",
39
+ "claim",
40
+ "--task",
41
+ taskId,
42
+ "--by",
43
+ by,
44
+ "--msg",
45
+ "auto-run",
46
+ "--allow-multiple-doing",
47
+ ];
48
+ if (projectId)
49
+ args.push("--project", projectId);
50
+ return spawnSelf(args);
51
+ }
52
+ export function spawnComplete(projectId, taskId, by) {
53
+ const args = ["exec", "complete", "--task", taskId, "--by", by, "--msg", "auto-complete"];
54
+ if (projectId)
55
+ args.push("--project", projectId);
56
+ spawnSelf(args);
57
+ }
58
+ // Release a just-made claim (doing → todo) when setup fails after the claim, so the task is not
59
+ // stranded in "doing" with no worktree. Uses the claiming actor, so no cross-actor override needed.
60
+ export function spawnRelease(projectId, taskId, by, reason) {
61
+ const args = [
62
+ "exec",
63
+ "release",
64
+ "--task",
65
+ taskId,
66
+ "--by",
67
+ by,
68
+ "--msg",
69
+ reason,
70
+ "--allow-multiple-doing",
71
+ ];
72
+ if (projectId)
73
+ args.push("--project", projectId);
74
+ spawnSelf(args);
75
+ }
76
+ // block 上限。block イベントログを読みやすく保つため、stderr から取り出した理由を切り詰める。
77
+ export function pipelineRecoveryMeta(input) {
78
+ return {
79
+ pipeline_stage: input.stage,
80
+ ...(input.evidenceRef ? { evidence_ref: input.evidenceRef } : {}),
81
+ ...(input.stateRef ? { pipeline_state_ref: input.stateRef } : {}),
82
+ ...(input.runId ? { pipeline_run_id: input.runId } : {}),
83
+ };
84
+ }
85
+ export function spawnBlock(projectId, taskId, by, reason, meta = { limit_deferred: "false" }) {
86
+ const args = ["exec", "block", "--task", taskId, "--by", by, "--msg", reason];
87
+ for (const [key, value] of Object.entries(meta))
88
+ args.push("--meta", `${key}=${value}`);
89
+ if (projectId)
90
+ args.push("--project", projectId);
91
+ spawnSelf(args);
92
+ }
93
+ export function repoRelativePath(repoRoot, path) {
94
+ return relative(repoRoot, path).split(sep).join("/");
95
+ }
96
+ // commitlint (config-conventional) rejects headers longer than 100 characters. Task names and
97
+ // register titles are free text, so clip the subject instead of failing the commit or merge.
98
+ const COMMIT_SUBJECT_MAX_LENGTH = 100;
99
+ export function commitSubject(prefix, title) {
100
+ const flat = title.replace(/\s+/g, " ").trim();
101
+ const subject = `${prefix}${flat}`;
102
+ if (subject.length <= COMMIT_SUBJECT_MAX_LENGTH)
103
+ return subject;
104
+ return `${subject.slice(0, COMMIT_SUBJECT_MAX_LENGTH - 1)}…`;
105
+ }
106
+ // 統合段(commit → merge → worktree 撤去)の進捗を pipeline-state へ記録する。Schedule は
107
+ // succeeded を exec branch へ commit してから merge し、register は開始と失敗を worktree に
108
+ // 記録する。記帳の失敗で統合自体を止めない。
109
+ export function recordIntegrateStage(statePath, updatedAt, buildPatch) {
110
+ if (!statePath || !existsSync(statePath))
111
+ return;
112
+ try {
113
+ const state = readPipelineState(statePath);
114
+ const patch = buildPatch(state.stages.integrate);
115
+ writePipelineState(statePath, updatePipelineStage(state, "integrate", patch, updatedAt));
116
+ }
117
+ catch (error) {
118
+ process.stderr.write(`warning: could not record the integrate stage in ${statePath}: ` +
119
+ `${error instanceof Error ? error.message : String(error)}\n`);
120
+ }
121
+ }
122
+ // 複数リポジトリ統合の進捗を同じ pipeline state へ追記する。プロダクトを統合するたびに
123
+ // project worktree 側へ書くため、途中で失敗しても `--resume` は Git の実状態とこの記録の両方を
124
+ // 手掛かりに、統合済みリポジトリを飛ばせる。
125
+ export function recordRepoIntegration(statePath, repo, patch) {
126
+ if (!statePath || !existsSync(statePath))
127
+ return;
128
+ const updatedAt = new Date().toISOString();
129
+ try {
130
+ const state = readPipelineState(statePath);
131
+ writePipelineState(statePath, updatePipelineRepoIntegration(state, repo, patch, updatedAt));
132
+ }
133
+ catch (error) {
134
+ process.stderr.write(`warning: could not record repository ${repo} in ${statePath}: ` +
135
+ `${error instanceof Error ? error.message : String(error)}\n`);
136
+ }
137
+ }
138
+ export function integrateLogPath(statePath) {
139
+ return statePath ? join(dirname(statePath), "integrate.log") : undefined;
140
+ }
@@ -0,0 +1,252 @@
1
+ import { loadExecDefaultsConfig } from "../agent-config.js";
2
+ import { resolveProjectPaths } from "../project.js";
3
+ import { isRegisterFailureMode } from "../register.js";
4
+ import { EXCLUSIVE_EXEC_RUN, parseParallel, resolveExecDefaultsPath, resolveRegisterWorktree, withProjectExecRunLock, } from "./shared.js";
5
+ import { runBatchMode, runManualMode } from "./schedule-mode.js";
6
+ import { runInPlaceMode } from "./in-place.js";
7
+ import { runJobMode } from "./job.js";
8
+ import { spawnRefresh, spawnValidate } from "./mode-shared.js";
9
+ import { resolveRegisterPipelineCommand } from "./register-core.js";
10
+ import { runRegisterMode } from "./register-mode.js";
11
+ export function registerRunCommand(exec) {
12
+ const rcmd = exec
13
+ .command("run")
14
+ .description("Run AI agent for a ready task (--auto selects next by strategy)");
15
+ rcmd.option("--project <projectId>", "Project id in .specdojo/specdojo.config.json");
16
+ rcmd.option("--by <nickname>", "Select an agent-members.yaml agent for a manual target");
17
+ rcmd.option("--auto", "Automatically select and run next ready task", false);
18
+ rcmd.option("--task <taskId>", "Task ID to run (manual selection)");
19
+ rcmd.option("--deliverable <localId>", "Catalog deliverable local_id target (unique project-wide)");
20
+ rcmd.option("--plan <path>", "Run an existing plan file (in-place; no generation)");
21
+ rcmd.option("--register <pjrIds...>", "One or more project register item IDs (PJR-XXXX) to run; execution location defaults to run.register_execution in exec-defaults (in-place when unset)");
22
+ rcmd.option("--register-filter", "Select register items deterministically with --register-types/--register-priorities/--register-statuses/--register-limit", false);
23
+ rcmd.option("--register-types <types>", "Comma-separated register item types");
24
+ rcmd.option("--register-priorities <priorities>", "Comma-separated register priorities");
25
+ rcmd.option("--register-statuses <statuses>", "Comma-separated register statuses");
26
+ rcmd.option("--register-limit <n>", "Maximum selected register items");
27
+ rcmd.option("--job <jobId>", "Materialize and run a reusable job definition");
28
+ rcmd.option("--input <key=value...>", "Job input values (repeat or provide multiple key=value pairs)");
29
+ rcmd.option("--scheduled-at <dateTime>", "Scheduled occurrence time for a Job Run");
30
+ rcmd.option("--job-trigger <source>", "Job trigger source: manual|routine|ci", "manual");
31
+ rcmd.option("--register-commit", "With in-place --register: commit each successful item's changes as a separate commit (default: leave changes in the working tree). Ignored in worktree mode, which always commits", false);
32
+ rcmd.option("--on-failure <mode>", "With --register: stop|continue remaining items after a failure (default: stop)");
33
+ rcmd.option("--resume", "With register worktree mode: resume the stage where a run stopped (executor, reporter, or integration), reusing the existing worktree and checkpoints", false);
34
+ rcmd.option("--resume-from <stage>", "With --resume: resume a reporter-stage run from executor instead (accepted value: executor)");
35
+ rcmd.option("--force-restart", "With register worktree mode: re-run the whole item even when a resumable executor result exists (discards the worktree and its uncommitted changes)", false);
36
+ rcmd.option("--worktree", "Use a git worktree and integrate back (requires --task, --register, or --job; Job runs are committed and reviewed before merge)", false);
37
+ rcmd.option("--in-place", "Run a register item in the current working tree (overrides run.register_execution; cannot be combined with --worktree)", false);
38
+ rcmd.option("--track-state", "Record claim/complete events (requires --task; --by optional, actor auto-derived from the resolved agent)", false);
39
+ rcmd.option("--archive-on-success", "Archive the generated plan to exec/plans/done/ after a successful in-place run", false);
40
+ rcmd.option("--parallel <n>", "Number of worktree instances to run in parallel", "1");
41
+ rcmd.option("--worktree-base <path>", "Override worktree base directory");
42
+ rcmd.option("--strategy <s>", "Task selection strategy: critical-first|fifo (default: critical-first)");
43
+ rcmd.option("--loop", "Repeat rounds until no ready tasks remain, rebuilding doc-index and running exec refresh between rounds", false);
44
+ rcmd.option("--max-rounds <n>", "Maximum number of rounds when using --loop (ignored without --loop)");
45
+ rcmd.option("--if-busy <policy>", "When another exec is running for the project: skip|wait|fail (default: fail)", "fail");
46
+ rcmd.option("--join", "With register worktree mode: run next to a running register worktree exec instead of waiting for it, sharing its provider caps, lifecycle serialization, and parent-validation slots (up to run.max_concurrent_runs; --if-busy applies when all join slots are taken)", false);
47
+ rcmd.option("--exec-defaults <path>", "Path to exec-defaults.yaml global config (default: .specdojo/exec-defaults.yaml)");
48
+ rcmd.option("--agent-config <path>", "Deprecated alias for --exec-defaults");
49
+ rcmd.option("--edit-by <nickname>", "agent-members.yaml nickname for edit-mode tasks in --auto batch runs");
50
+ rcmd.option("--review-by <nickname>", "agent-members.yaml nickname for review-mode tasks in --auto batch runs");
51
+ rcmd.option("--executor-by <nickname>", "Executor nickname; with --register, also accepts PJR-ID=nickname assignments separated by commas. With --plan / --deliverable, runs the executor/reporter pipeline");
52
+ rcmd.option("--reporter-by <nickname>", "agent-members.yaml reporter nickname for agent_pipeline tasks (with --plan / --deliverable, runs the executor/reporter pipeline)");
53
+ rcmd.option("--on-rate-limit <action>", "Pinned-agent rate-limit action: stop|wait|fallback (overrides rate_limit_policy.pinned)");
54
+ rcmd.option("--fallback-executor-by <nickname>", "Fallback executor used when --on-rate-limit fallback is selected");
55
+ rcmd.option("--fallback-reporter-by <nickname>", "Fallback reporter used when --on-rate-limit fallback is selected");
56
+ rcmd.option("--dry-run", "Print resolved command without executing", false);
57
+ rcmd.action(async (opts) => {
58
+ try {
59
+ const isAuto = !!opts.auto;
60
+ const hasTask = !!opts.task;
61
+ const hasDeliverable = !!opts.deliverable;
62
+ const hasPlan = !!opts.plan;
63
+ const hasRegisterIds = !!opts.register;
64
+ const hasRegisterFilter = !!opts.registerFilter;
65
+ const hasRegister = hasRegisterIds || hasRegisterFilter;
66
+ const hasJob = !!opts.job;
67
+ const isManual = hasTask || hasDeliverable || hasPlan || hasRegister || hasJob;
68
+ const isBatch = isAuto;
69
+ if (hasRegisterIds && hasRegisterFilter) {
70
+ process.stdout.write("Specify either --register or --register-filter, not both.\n");
71
+ process.exitCode = 1;
72
+ return;
73
+ }
74
+ if ((opts.registerTypes ||
75
+ opts.registerPriorities ||
76
+ opts.registerStatuses ||
77
+ opts.registerLimit) &&
78
+ !hasRegisterFilter) {
79
+ process.stdout.write("--register-types, --register-priorities, --register-statuses, and --register-limit require --register-filter.\n");
80
+ process.exitCode = 1;
81
+ return;
82
+ }
83
+ if (!isAuto && !isManual) {
84
+ process.stdout.write("Specify --auto, --by (with a manual target), --task, --deliverable, --plan, --register, or --job.\n");
85
+ process.exitCode = 1;
86
+ return;
87
+ }
88
+ if ([hasTask, hasDeliverable, hasPlan, hasRegister, hasJob].filter(Boolean).length > 1) {
89
+ process.stdout.write("Specify at most one of --task, --deliverable, --plan, --register, --job.\n");
90
+ process.exitCode = 1;
91
+ return;
92
+ }
93
+ if (hasRegister && opts.trackState) {
94
+ process.stdout.write("--track-state cannot be used with --register (state is tracked in the register itself).\n");
95
+ process.exitCode = 1;
96
+ return;
97
+ }
98
+ if (opts.worktree && opts.inPlace) {
99
+ process.stdout.write("Specify either --worktree or --in-place, not both.\n");
100
+ process.exitCode = 1;
101
+ return;
102
+ }
103
+ if (opts.inPlace && !hasRegister) {
104
+ process.stdout.write("--in-place requires --register or --register-filter.\n");
105
+ process.exitCode = 1;
106
+ return;
107
+ }
108
+ if (hasRegister) {
109
+ const { schedulePath, executionPath } = resolveProjectPaths({ project: opts.project });
110
+ const execDefaults = loadExecDefaultsConfig(resolveExecDefaultsPath(opts, schedulePath), executionPath);
111
+ opts.worktree = resolveRegisterWorktree(opts, execDefaults);
112
+ }
113
+ if (hasRegister && !opts.worktree && parseParallel(opts.parallel) !== 1) {
114
+ process.stdout.write("--parallel with --register requires worktree mode; use --worktree or configure run.register_execution: worktree.\n");
115
+ process.exitCode = 1;
116
+ return;
117
+ }
118
+ if (opts.join && !(hasRegister && opts.worktree)) {
119
+ process.stdout.write("--join requires --register (or --register-filter) in worktree mode.\n");
120
+ process.exitCode = 1;
121
+ return;
122
+ }
123
+ if (hasRegister && opts.worktree && opts.registerCommit) {
124
+ process.stdout.write("Note: --register-commit is ignored in worktree mode; worktree runs always commit (checkpoint + merge back).\n");
125
+ }
126
+ if ((opts.registerCommit || opts.onFailure) && !hasRegister) {
127
+ process.stdout.write("--register-commit and --on-failure require --register.\n");
128
+ process.exitCode = 1;
129
+ return;
130
+ }
131
+ if ((opts.resume || opts.forceRestart) && !hasRegister) {
132
+ process.stdout.write("--resume and --force-restart require --register.\n");
133
+ process.exitCode = 1;
134
+ return;
135
+ }
136
+ if (opts.resumeFrom && !opts.resume) {
137
+ process.stdout.write("--resume-from requires --resume.\n");
138
+ process.exitCode = 1;
139
+ return;
140
+ }
141
+ if (opts.resumeFrom && opts.resumeFrom !== "executor") {
142
+ process.stdout.write('--resume-from must be "executor".\n');
143
+ process.exitCode = 1;
144
+ return;
145
+ }
146
+ // 再開は既存 worktree の成果を再利用する操作のため、worktree 実行に限る。in-place 実行は
147
+ // executor の変更が作業ツリーに残り、再開時のID単位 commit が対象を判別できない。
148
+ if ((opts.resume || opts.forceRestart) && !opts.worktree) {
149
+ process.stdout.write("--resume and --force-restart require register worktree mode; use --worktree or configure run.register_execution: worktree.\n");
150
+ process.exitCode = 1;
151
+ return;
152
+ }
153
+ if (opts.resume && opts.forceRestart) {
154
+ process.stdout.write("Specify either --resume or --force-restart, not both.\n");
155
+ process.exitCode = 1;
156
+ return;
157
+ }
158
+ if ((opts.input || opts.scheduledAt) && !hasJob) {
159
+ process.stdout.write("--input and --scheduled-at require --job.\n");
160
+ process.exitCode = 1;
161
+ return;
162
+ }
163
+ if (opts.jobTrigger && !["manual", "routine", "ci"].includes(opts.jobTrigger)) {
164
+ process.stdout.write("--job-trigger must be manual, routine, or ci.\n");
165
+ process.exitCode = 1;
166
+ return;
167
+ }
168
+ if (opts.onFailure && !isRegisterFailureMode(opts.onFailure)) {
169
+ process.stdout.write(`--on-failure must be "stop" or "continue": ${opts.onFailure}\n`);
170
+ process.exitCode = 1;
171
+ return;
172
+ }
173
+ if (isAuto && isManual) {
174
+ process.stdout.write("Specify either --auto or a manual target, not both.\n");
175
+ process.exitCode = 1;
176
+ return;
177
+ }
178
+ if (isAuto && opts.by) {
179
+ process.stdout.write("--by requires a manual target; use --edit-by / --review-by with --auto.\n");
180
+ process.exitCode = 1;
181
+ return;
182
+ }
183
+ if (opts.by && opts.executorBy) {
184
+ process.stdout.write("Specify either --by or --executor-by, not both.\n");
185
+ process.exitCode = 1;
186
+ return;
187
+ }
188
+ if (opts.onRateLimit && !["stop", "wait", "fallback"].includes(opts.onRateLimit)) {
189
+ process.stdout.write('--on-rate-limit must be "stop", "wait", or "fallback".\n');
190
+ process.exitCode = 1;
191
+ return;
192
+ }
193
+ if (opts.worktree && !hasTask && !hasRegister && !hasJob) {
194
+ process.stdout.write("--worktree requires --task, --register, or --job.\n");
195
+ process.exitCode = 1;
196
+ return;
197
+ }
198
+ // --parallel is allowed for register worktree runs (handled above); reject it for other
199
+ // manual targets, which run a single instance.
200
+ if (isManual && !hasRegister && parseParallel(opts.parallel) !== 1) {
201
+ process.stdout.write("--parallel cannot be used with a manual target.\n");
202
+ process.exitCode = 1;
203
+ return;
204
+ }
205
+ // register worktree 実行だけが共有資源をプロセス横断で統制するため、後から --join する
206
+ // run を受け入れる。それ以外の run は従来どおり project 全体を排他する。
207
+ const registerWorktreeLockSharing = hasRegister && opts.worktree ? { shareable: true, join: !!opts.join } : EXCLUSIVE_EXEC_RUN;
208
+ await withProjectExecRunLock(opts, "run", async () => {
209
+ // Register-item run: use the configured location or an explicit CLI override, with state tracked
210
+ // via register transitions (start → review / waiting) instead of exec events.
211
+ if (hasRegister) {
212
+ await runRegisterMode(opts);
213
+ return;
214
+ }
215
+ if (hasJob) {
216
+ await runJobMode(opts, resolveRegisterPipelineCommand);
217
+ return;
218
+ }
219
+ // In-place manual run (default): generate the plan on demand and run in the
220
+ // current repository. No validate/refresh pass — that is orchestration only.
221
+ if (isManual && !opts.worktree) {
222
+ await runInPlaceMode(opts);
223
+ return;
224
+ }
225
+ process.stdout.write("[run] validate...\n");
226
+ if (!spawnValidate(opts.project)) {
227
+ process.stdout.write("[run] validate failed — exit\n");
228
+ process.exitCode = 1;
229
+ return;
230
+ }
231
+ process.stdout.write("[run] validate: ok\n[run] refresh...\n");
232
+ if (!spawnRefresh(opts.project)) {
233
+ process.stdout.write("[run] refresh failed — exit\n");
234
+ process.exitCode = 1;
235
+ return;
236
+ }
237
+ process.stdout.write("[run] refresh: ok\n");
238
+ if (isBatch) {
239
+ await runBatchMode(opts);
240
+ }
241
+ else {
242
+ await runManualMode(opts);
243
+ }
244
+ }, registerWorktreeLockSharing);
245
+ }
246
+ catch (error) {
247
+ const message = error instanceof Error ? error.message : String(error);
248
+ process.stdout.write(message + "\n");
249
+ process.exitCode = 1;
250
+ }
251
+ });
252
+ }