specdojo 0.2.1 → 0.3.1

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 (242) hide show
  1. package/.github/agents/specdojo-orchestrator.md +165 -0
  2. package/CHANGELOG.md +298 -0
  3. package/README.md +92 -42
  4. package/dist/agent-response.js +20 -0
  5. package/dist/agent.js +4 -4
  6. package/dist/build-command.js +28 -8
  7. package/dist/catalog-build-references.js +144 -0
  8. package/dist/catalog-build-render.js +144 -0
  9. package/dist/catalog-build.js +13 -290
  10. package/dist/catalog-generate.js +6 -9
  11. package/dist/catalog-plan-generate.js +2 -2
  12. package/dist/catalog-plan.js +6 -6
  13. package/dist/catalog-scaffold.js +4 -4
  14. package/dist/catalog.js +2 -2
  15. package/dist/dashboard-exec-records.js +105 -0
  16. package/dist/dashboard-routines.js +255 -0
  17. package/dist/dashboard-shared.js +14 -0
  18. package/dist/dashboard-timeline.js +175 -0
  19. package/dist/dashboard.js +31 -444
  20. package/dist/deliverable-trash.js +3 -3
  21. package/dist/devcontainer-command.js +43 -0
  22. package/dist/devcontainer-scaffold.js +165 -0
  23. package/dist/doc-index.js +3 -3
  24. package/dist/exec-agent-config.js +107 -9
  25. package/dist/exec-agent-git-state.js +18 -0
  26. package/dist/exec-agent-protected-config.js +46 -8
  27. package/dist/exec-commands.js +557 -0
  28. package/dist/exec-core.js +457 -0
  29. package/dist/exec-evidence.js +254 -11
  30. package/dist/exec-handoff.js +336 -0
  31. package/dist/exec-parent-validation.js +317 -43
  32. package/dist/exec-pipeline-state.js +74 -9
  33. package/dist/exec-plans-core.js +693 -0
  34. package/dist/exec-plans-generation.js +206 -0
  35. package/dist/exec-plans-storage.js +131 -0
  36. package/dist/exec-plans.js +3 -1016
  37. package/dist/exec-protection-handoff.js +43 -2
  38. package/dist/exec-provider-scaffold.js +247 -15
  39. package/dist/exec-register-resume.js +65 -19
  40. package/dist/exec-register.js +9 -3
  41. package/dist/exec-repo-integration-git.js +23 -0
  42. package/dist/exec-repo-integration-sync.js +264 -0
  43. package/dist/exec-repo-integration.js +534 -0
  44. package/dist/exec-repo-trace.js +182 -0
  45. package/dist/exec-reporter-output.js +206 -0
  46. package/dist/exec-reporter.js +525 -248
  47. package/dist/exec-results.js +103 -71
  48. package/dist/exec-run-agent-pipeline.js +256 -0
  49. package/dist/exec-run-agent.js +531 -0
  50. package/dist/exec-run-in-place.js +541 -0
  51. package/dist/exec-run-job.js +717 -0
  52. package/dist/exec-run-lifecycle-commands.js +522 -0
  53. package/dist/exec-run-lock.js +110 -107
  54. package/dist/exec-run-mode-shared.js +140 -0
  55. package/dist/exec-run-register-command.js +244 -0
  56. package/dist/exec-run-register-core.js +386 -0
  57. package/dist/exec-run-register-mode.js +206 -0
  58. package/dist/exec-run-register-resume.js +393 -0
  59. package/dist/exec-run-register-state.js +322 -0
  60. package/dist/exec-run-register-worktree.js +509 -0
  61. package/dist/exec-run-schedule-mode.js +294 -0
  62. package/dist/exec-run-schedule-prepare.js +353 -0
  63. package/dist/exec-run-schedule-task.js +572 -0
  64. package/dist/exec-run-shared.js +399 -0
  65. package/dist/exec-run.js +11 -4953
  66. package/dist/exec-shared.js +9 -2
  67. package/dist/exec-slot-lock.js +242 -0
  68. package/dist/exec-task-repos.js +415 -0
  69. package/dist/exec-trial-commands.js +558 -0
  70. package/dist/exec-trial-core.js +371 -0
  71. package/dist/exec-trial.js +2 -895
  72. package/dist/exec-worktree-command.js +87 -43
  73. package/dist/exec-worktree-ops-commit.js +707 -0
  74. package/dist/exec-worktree-ops-lifecycle.js +292 -0
  75. package/dist/exec-worktree-ops-merge.js +303 -0
  76. package/dist/exec-worktree-ops.js +3 -847
  77. package/dist/exec-worktree.js +146 -31
  78. package/dist/exec.js +2 -999
  79. package/dist/frontmatter-namespace.js +2 -2
  80. package/dist/grade-apply.js +734 -0
  81. package/dist/grade-command-apply.js +250 -0
  82. package/dist/grade-command-inspect.js +138 -0
  83. package/dist/grade-command-plan.js +101 -0
  84. package/dist/grade-command-shared.js +68 -0
  85. package/dist/grade-core.js +307 -0
  86. package/dist/grade-markdown.js +274 -0
  87. package/dist/grade-pipeline-state.js +184 -0
  88. package/dist/grade-plan.js +507 -0
  89. package/dist/grade-result.js +133 -5
  90. package/dist/grade-target-discovery.js +265 -0
  91. package/dist/grade-targets.js +432 -0
  92. package/dist/grade.js +14 -2451
  93. package/dist/init-command.js +443 -0
  94. package/dist/job-definition.js +670 -0
  95. package/dist/job.js +64 -578
  96. package/dist/kata-command.js +2 -2
  97. package/dist/orchestrator.js +213 -0
  98. package/dist/register-command-types.js +1 -0
  99. package/dist/register-core.js +363 -0
  100. package/dist/register-create-commands.js +245 -0
  101. package/dist/register-event-merge.js +169 -0
  102. package/dist/register-events.js +4 -4
  103. package/dist/register-item.js +13 -7
  104. package/dist/register-maintenance-commands.js +187 -0
  105. package/dist/register-migration.js +268 -0
  106. package/dist/register-renumber.js +314 -0
  107. package/dist/register-transition-commands.js +248 -0
  108. package/dist/register-update.js +230 -0
  109. package/dist/register-views.js +256 -0
  110. package/dist/register.js +175 -1975
  111. package/dist/review-grade.js +252 -0
  112. package/dist/review-plan.js +114 -4
  113. package/dist/review-types.js +40 -1
  114. package/dist/routine-definition.js +401 -0
  115. package/dist/routine.js +73 -402
  116. package/dist/schedule-approach.js +2 -2
  117. package/dist/schedule-build.js +2 -2
  118. package/dist/schedule-strategy-generate-document.js +273 -0
  119. package/dist/schedule-strategy-generate-scope.js +199 -0
  120. package/dist/schedule-strategy-generate.js +9 -473
  121. package/dist/schedule.js +19 -6
  122. package/dist/specdojo-config.js +465 -20
  123. package/dist/specdojo-gitignore.js +135 -0
  124. package/dist/specdojo.js +6 -0
  125. package/dist/viewpoint-document-kinds-check.js +128 -0
  126. package/dist/yaml-pages.js +4 -4
  127. package/dist/yaml.js +28 -0
  128. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +348 -90
  129. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +51 -17
  130. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +7 -5
  131. package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +29 -31
  132. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +34 -55
  133. package/docs/ja/specdojo/exec-templates/xrp-job-template.md +54 -0
  134. package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +28 -37
  135. package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +29 -34
  136. package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +30 -30
  137. package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +29 -34
  138. package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +29 -34
  139. package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +29 -34
  140. package/docs/ja/specdojo/exec-templates/xrp-template.md +29 -28
  141. package/docs/ja/specdojo/exec-templates/xrr-template.md +11 -9
  142. package/docs/ja/specdojo/guides/docs-editing-guide.md +20 -0
  143. package/docs/ja/specdojo/guides/docs-structure-guide.md +103 -70
  144. package/docs/ja/specdojo/guides/exec-config-guide.md +93 -49
  145. package/docs/ja/specdojo/guides/exec-operation-guide.md +124 -27
  146. package/docs/ja/specdojo/guides/exec-worktree-guide.md +40 -11
  147. package/docs/ja/specdojo/guides/kata-guide.md +4 -4
  148. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +45 -22
  149. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +1 -1
  150. package/docs/ja/specdojo/guides/practice-system-composition-guide.md +13 -13
  151. package/docs/ja/specdojo/guides/quick-start-guide.md +260 -30
  152. package/docs/ja/specdojo/guides/register-operation-guide.md +31 -14
  153. package/docs/ja/specdojo/guides/release-v0-3-0-migration-guide.md +264 -0
  154. package/docs/ja/specdojo/guides/remote-host-development-guide.md +22 -1
  155. package/docs/ja/specdojo/guides/review-guide.md +195 -158
  156. package/docs/ja/specdojo/guides/routine-operation-guide.md +75 -10
  157. package/docs/ja/specdojo/guides/ryu-guide.md +32 -30
  158. package/docs/ja/specdojo/guides/schedule-design-guide.md +10 -10
  159. package/docs/ja/specdojo/guides/schedule-operation-guide.md +1 -1
  160. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +58 -33
  161. package/docs/ja/specdojo/guides/use-case-guide.md +3 -3
  162. package/docs/ja/specdojo/guides/waza-guide.md +15 -2
  163. package/docs/ja/specdojo/index.md +2 -2
  164. package/docs/ja/specdojo/philosophy/specdojo-philosophy.md +5 -5
  165. package/docs/ja/specdojo/recipes/bps-recipe.md +213 -0
  166. package/docs/ja/specdojo/recipes/pm-members-recipe.md +52 -117
  167. package/docs/ja/specdojo/references/command-reference.md +335 -92
  168. package/docs/ja/specdojo/references/deliverables-reference.md +1 -1
  169. package/docs/ja/specdojo/references/directory-layout-reference.md +13 -9
  170. package/docs/ja/specdojo/references/specdojo-config-reference.md +107 -24
  171. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +132 -220
  172. package/docs/ja/specdojo/rulebooks/br-rulebook.md +6 -44
  173. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +2 -0
  174. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +0 -87
  175. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +61 -39
  176. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +0 -87
  177. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +1 -33
  178. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +0 -137
  179. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +0 -247
  180. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +0 -83
  181. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +4 -2
  182. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +78 -150
  183. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +5 -4
  184. package/docs/ja/specdojo/rulebooks/sch-rulebook.md +1 -1
  185. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +0 -11
  186. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +0 -61
  187. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +2 -47
  188. package/docs/ja/specdojo/samples/bps-sample.md +74 -21
  189. package/docs/ja/specdojo/samples/gl-sample.yaml +17 -1
  190. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +28 -0
  191. package/docs/ja/specdojo/samples/pm-members-sample.yaml +2 -67
  192. package/docs/ja/specdojo/samples/pm-organization-sample.md +8 -7
  193. package/docs/ja/specdojo/samples/pm-raci-sample.md +1 -1
  194. package/docs/ja/specdojo/samples/tml-sample.yaml +40 -0
  195. package/docs/ja/specdojo/standards/document-metadata-standard.md +21 -16
  196. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +14 -14
  197. package/docs/ja/specdojo/standards/job-definition-standard.md +37 -17
  198. package/docs/ja/specdojo/standards/people-and-organization-definition-standard.md +37 -32
  199. package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +1 -1
  200. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +21 -11
  201. package/docs/ja/specdojo/templates/agent-members-template.yaml +25 -0
  202. package/docs/ja/specdojo/templates/bps-template.md +91 -0
  203. package/docs/ja/specdojo/templates/pm-members-template.yaml +2 -59
  204. package/docs/specdojo/schemas/v1/agent-members.schema.yaml +76 -0
  205. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +4 -2
  206. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +55 -2
  207. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +93 -6
  208. package/docs/specdojo/schemas/v1/exec-reporter-output.schema.yaml +27 -78
  209. package/docs/specdojo/schemas/v1/gl.schema.yaml +87 -0
  210. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +33 -0
  211. package/docs/specdojo/schemas/v1/job-run.schema.yaml +27 -0
  212. package/docs/specdojo/schemas/v1/job.schema.yaml +25 -0
  213. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +49 -1
  214. package/docs/specdojo/schemas/v1/pm-members.schema.yaml +9 -169
  215. package/docs/specdojo/schemas/v1/pm-review-viewpoints.schema.yaml +100 -10
  216. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +13 -0
  217. package/docs/specdojo/schemas/v1/routine-run.schema.yaml +3 -0
  218. package/docs/specdojo/schemas/v1/routine.schema.yaml +7 -0
  219. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +110 -0
  220. package/package.json +17 -12
  221. package/templates/antigravity/README.md +29 -4
  222. package/templates/antigravity/{pm-members-snippet.yaml → agent-members-snippet.yaml} +8 -2
  223. package/templates/antigravity/exec-defaults-snippet.yaml +10 -7
  224. package/templates/antigravity/orchestrator.md +18 -7
  225. package/templates/antigravity/settings.global.json +55 -0
  226. package/templates/claude/agents/claude-executor.md +14 -0
  227. package/templates/claude/agents/claude-reporter.md +16 -0
  228. package/templates/claude/agents/specdojo-orchestrator.md +18 -7
  229. package/templates/claude/settings.edit.json +27 -1
  230. package/templates/codex/README.md +5 -4
  231. package/templates/codex/agents/specdojo-orchestrator.toml +18 -7
  232. package/templates/codex/orchestrator.md +18 -7
  233. package/templates/copilot/README.md +7 -5
  234. package/templates/copilot/{pm-members-snippet.yaml → agent-members-snippet.yaml} +4 -2
  235. package/templates/devcontainer/devcontainer.json +27 -0
  236. package/templates/devcontainer/emacs/init.el +88 -0
  237. package/templates/devcontainer/post-create.sh +62 -0
  238. package/templates/init-agent-members.yaml +200 -0
  239. package/templates/init-exec-defaults.yaml +74 -0
  240. package/templates/opencode/agents/specdojo-orchestrator.md +18 -7
  241. package/docs/ja/specdojo/exec-templates/xrp-viewpoint-detail-template.md +0 -7
  242. package/docs/ja/specdojo/exec-templates/xrr-viewpoint-detail-template.md +0 -7
@@ -0,0 +1,457 @@
1
+ import { acquireSchedulerLock, buildEvent, canReleaseTask, collectRepeatable, findDoingTasksForActor, foldEventsToState, readAllEventFiles, releaseSchedulerLock, writeEventFile, } from "./exec-events.js";
2
+ import { activateResolvedProjectPaths, resolveProjectPaths } from "./exec-project.js";
3
+ import { assertValidActor, loadConfig, loadMemberRoster, specdojoRootDir, } from "./specdojo-config.js";
4
+ import { buildScheduleIndex, computeCpm, exitWithCode, printValidateResult, validateAll, writeCpmFiles, writeGeneratedCore, writeScheduleHashAndDiff, } from "./exec-schedule.js";
5
+ import { qualifyTaskId, requireNonEmpty } from "./exec-shared.js";
6
+ import { finalizeResultSectionsForDeliverable, targetDocIdsForScheduledTask, } from "./exec-plans.js";
7
+ import { resetResultForClaim, scaffoldResult } from "./exec-results.js";
8
+ import { discardStaleExecWorktree } from "./exec-worktree-ops.js";
9
+ import { configuredProductRepos } from "./exec-task-repos.js";
10
+ import { buildInitialStateFromStrategy } from "./exec-schedule-initial.js";
11
+ import { buildPhaseModeIndex, resolveApproach, resolveTaskExecution, resolveTaskMode, } from "./exec-strategy.js";
12
+ export const KNOWN_OWNER_LABELS = ["PO", "PM", "BA", "ARC", "DEV", "QE", "UX", "OPS"];
13
+ export const KNOWN_OWNER_LABELS_TEXT = KNOWN_OWNER_LABELS.join("|");
14
+ const KNOWN_APPROACHES = [
15
+ "fully-guided",
16
+ "recipe-guided",
17
+ "freeform",
18
+ "bootstrap",
19
+ "retrofit",
20
+ "cross-deliverable-dedup",
21
+ "rulebook-maintenance",
22
+ "recipe-maintenance",
23
+ "sample-maintenance",
24
+ "template-maintenance",
25
+ "finalize",
26
+ "bootstrap-finalize",
27
+ ];
28
+ export function parseTaskMode(value) {
29
+ const mode = typeof value === "string" ? value.trim().toLowerCase() : "edit";
30
+ if (mode !== "edit" && mode !== "review") {
31
+ throw new Error(`Invalid --mode value: ${mode}. Use one of: edit|review.`);
32
+ }
33
+ return mode;
34
+ }
35
+ export function parseApproach(value) {
36
+ const approach = typeof value === "string" ? value.trim().toLowerCase() : "";
37
+ if (!KNOWN_APPROACHES.includes(approach)) {
38
+ throw new Error(`Invalid --approach value: ${approach}. Use one of: ${KNOWN_APPROACHES.join("|")}.`);
39
+ }
40
+ return approach;
41
+ }
42
+ export function addProjectOptions(cmd) {
43
+ return cmd.option("--project <projectId>", "Project id in specdojo.config.json (e.g. shj-0001)");
44
+ }
45
+ export function addLockOptions(cmd) {
46
+ return cmd
47
+ .option("--allow-multiple-doing", "Allow this actor to hold multiple doing tasks", false)
48
+ .option("--lock-timeout-ms <ms>", "Lock acquisition timeout in ms", "10000")
49
+ .option("--lock-stale-ms <ms>", "Lock stale threshold in ms", "300000");
50
+ }
51
+ export function addForceOption(cmd) {
52
+ return cmd.option("--force", "Human actor only: override the guard on a task held by another actor", false);
53
+ }
54
+ export function addOwnerOptions(cmd) {
55
+ return cmd
56
+ .option("--owner <owner>", `Planned owner label for assignment checks (${KNOWN_OWNER_LABELS_TEXT}; defaults to SPECDOJO_OWNER, roster owner, or actor)`)
57
+ .option("--allow-owner-mismatch", "Allow claiming a task assigned to a different owner", false);
58
+ }
59
+ // Fixed default messages for routine state transitions. Events whose message carries the
60
+ // reason itself (note / block / unblock / reopen / cancel) have no default and keep --msg required.
61
+ export const DEFAULT_EVENT_MESSAGES = {
62
+ claim: "claim task",
63
+ complete: "complete task",
64
+ release: "release task",
65
+ link: "link refs",
66
+ estimate: "update estimate",
67
+ };
68
+ export function addCommonAddOptions(cmd, options) {
69
+ addProjectOptions(cmd);
70
+ // `release --all-blocked` operates on every blocked task instead of a single --task, so the task
71
+ // option must be optional for that command. The single-task path still validates it via
72
+ // requireNonEmpty before building the event.
73
+ if (options?.requireTask === false) {
74
+ cmd.option("--task <taskId>", "Task/Milestone ID");
75
+ }
76
+ else {
77
+ cmd.requiredOption("--task <taskId>", "Task/Milestone ID");
78
+ }
79
+ cmd.requiredOption("--by <actor>", "Actor (human/agent)");
80
+ if (options?.msgDefault !== undefined) {
81
+ cmd.option("--msg <message>", "Short message", options.msgDefault);
82
+ }
83
+ else {
84
+ cmd.requiredOption("--msg <message>", "Short message");
85
+ }
86
+ return cmd
87
+ .option("--run-id <id>", "Correlation id")
88
+ .option("--ref <k=v...>", "refs key=value (repeatable)", collectRepeatable, [])
89
+ .option("--meta <k=v...>", "meta key=value (repeatable)", collectRepeatable, [])
90
+ .option("--dry-run", "Print event JSON without writing to disk", false);
91
+ }
92
+ export function resolveProjectContext(opts) {
93
+ const resolvedPaths = resolveProjectPaths({ project: opts.project });
94
+ activateResolvedProjectPaths(resolvedPaths);
95
+ return resolvedPaths;
96
+ }
97
+ export function loadRosterForOpts(opts) {
98
+ const { config } = loadConfig();
99
+ if (!config)
100
+ return null;
101
+ const projectId = resolveProjectId(opts);
102
+ const project = config.projects[projectId];
103
+ if (!project)
104
+ return null;
105
+ return loadMemberRoster(specdojoRootDir(), project);
106
+ }
107
+ export function resolveProjectId(opts) {
108
+ const { config } = loadConfig();
109
+ return (opts.project?.trim() ||
110
+ process.env.SPECDOJO_PROJECT?.trim() ||
111
+ config?.current_project?.trim() ||
112
+ Object.keys(config?.projects ?? {})[0] ||
113
+ "");
114
+ }
115
+ export function findRosterMember(roster, actor) {
116
+ return roster?.members.find((member) => member.nickname === actor) ?? null;
117
+ }
118
+ // The --force override is honored only for actors registered as humans in the
119
+ // roster, so agents cannot steal a task another actor is working on.
120
+ export function resolveForceOverride(opts, actor) {
121
+ const isHuman = findRosterMember(loadRosterForOpts(opts), actor)?.type === "human";
122
+ return { isHuman, force: !!opts.force };
123
+ }
124
+ export function resolveClaimOwner(opts, actor, roster = null, taskOwner) {
125
+ const cliOwner = typeof opts.owner === "string" ? opts.owner.trim().toUpperCase() : "";
126
+ const envOwner = typeof process.env.SPECDOJO_OWNER === "string"
127
+ ? process.env.SPECDOJO_OWNER.trim().toUpperCase()
128
+ : "";
129
+ const rosterMemberRoles = findRosterMember(roster, actor)?.roles ?? [];
130
+ // For multi-role actors, prefer the role matching the task's planned owner.
131
+ const matchedRole = taskOwner && rosterMemberRoles.length > 1
132
+ ? (rosterMemberRoles
133
+ .find((r) => r.trim().toUpperCase() === taskOwner.toUpperCase() &&
134
+ KNOWN_OWNER_LABELS.includes(r.trim().toUpperCase()))
135
+ ?.trim()
136
+ .toUpperCase() ?? "")
137
+ : "";
138
+ const rosterOwner = Array.isArray(rosterMemberRoles) && rosterMemberRoles.length > 0
139
+ ? rosterMemberRoles[0].trim().toUpperCase()
140
+ : "";
141
+ if (cliOwner && !KNOWN_OWNER_LABELS.includes(cliOwner)) {
142
+ throw new Error(`Invalid --owner value: ${cliOwner}. Use one of: ${KNOWN_OWNER_LABELS_TEXT}.`);
143
+ }
144
+ if (envOwner && !KNOWN_OWNER_LABELS.includes(envOwner)) {
145
+ throw new Error(`Invalid SPECDOJO_OWNER value: ${envOwner}. Use one of: ${KNOWN_OWNER_LABELS_TEXT}.`);
146
+ }
147
+ if (rosterOwner &&
148
+ !KNOWN_OWNER_LABELS.includes(rosterOwner)) {
149
+ throw new Error(`Invalid roster owner for actor ${actor}: ${rosterOwner}. Use one of: ${KNOWN_OWNER_LABELS_TEXT}.`);
150
+ }
151
+ return cliOwner || envOwner || matchedRole || rosterOwner || "";
152
+ }
153
+ export function resolveSchedulerStrategy(opts, actor, roster = null) {
154
+ const cliStrategy = typeof opts.strategy === "string" ? opts.strategy.trim().toLowerCase() : "";
155
+ const rosterStrategy = findRosterMember(roster, actor)?.scheduler_strategy ?? "";
156
+ const strategy = (cliStrategy || rosterStrategy || "critical-first");
157
+ if (strategy !== "critical-first" && strategy !== "fifo") {
158
+ throw new Error(`Invalid --strategy value: ${strategy}. Use one of: critical-first|fifo.`);
159
+ }
160
+ return strategy;
161
+ }
162
+ export function printCommandError(error, fail = true) {
163
+ const message = error instanceof Error ? error.message : String(error);
164
+ process.stdout.write(message + "\n");
165
+ if (fail)
166
+ exitWithCode(false);
167
+ else
168
+ process.exitCode = 1;
169
+ }
170
+ export function loadValidatedExecState(projectPath) {
171
+ const res = validateAll(projectPath);
172
+ if (!res.ok) {
173
+ printValidateResult(res);
174
+ exitWithCode(false);
175
+ return null;
176
+ }
177
+ const schedule = buildScheduleIndex(projectPath);
178
+ const events = readAllEventFiles(projectPath);
179
+ const initialTasks = buildInitialStateFromStrategy(projectPath, schedule);
180
+ const snapshot = foldEventsToState(events, schedule, projectPath, initialTasks);
181
+ return { schedule, events, snapshot };
182
+ }
183
+ export function ensureActorCanClaimNext(snapshot, actor, allowMultipleDoing) {
184
+ const doingTasks = findDoingTasksForActor(snapshot, actor);
185
+ if (allowMultipleDoing || doingTasks.length === 0)
186
+ return true;
187
+ process.stdout.write(`Actor ${actor} already has doing task(s): ${doingTasks.join(", ")}\n` +
188
+ `Use --allow-multiple-doing to override.\n`);
189
+ exitWithCode(false);
190
+ return false;
191
+ }
192
+ export async function scaffoldClaimResult(opts) {
193
+ const scheduleNode = opts.state.schedule.nodes.get(opts.taskId);
194
+ const localId = scheduleNode?.local_id;
195
+ const phaseModeIndex = buildPhaseModeIndex(opts.schedulePath);
196
+ const mode = resolveTaskMode(localId, opts.taskId, phaseModeIndex, scheduleNode?.phase_suffix, scheduleNode?.phase_set);
197
+ const approach = resolveApproach(localId, opts.taskId, phaseModeIndex, scheduleNode?.phase_suffix, scheduleNode?.phase_set);
198
+ const execution = resolveTaskExecution(localId, opts.taskId, phaseModeIndex, scheduleNode?.phase_suffix, scheduleNode?.phase_set);
199
+ const finalizeSections = approach === "finalize" || approach === "bootstrap-finalize"
200
+ ? finalizeResultSectionsForDeliverable(opts.catalogPath ?? "", localId, approach)
201
+ : undefined;
202
+ const targets = targetDocIdsForScheduledTask(opts.catalogPath ?? "", {
203
+ local_id: localId,
204
+ target_local_ids: scheduleNode?.target_local_ids,
205
+ approach,
206
+ }, opts.projectId);
207
+ const result = await scaffoldResult({
208
+ executionPath: opts.executionPath,
209
+ taskId: opts.taskId,
210
+ mode,
211
+ projectId: opts.projectId,
212
+ ...(execution === "agent" ? { planRef: `exec/plans/${opts.taskId}-plan.md` } : {}),
213
+ agent: opts.actor,
214
+ startedAt: opts.startedAt,
215
+ execution,
216
+ ...(approach ? { approach } : {}),
217
+ ...(targets ? { targets } : {}),
218
+ ...(finalizeSections ? { finalizeSections } : {}),
219
+ });
220
+ if (!result.created) {
221
+ await resetResultForClaim(result.resultPath, opts.actor, opts.startedAt, execution);
222
+ }
223
+ }
224
+ export function runSimpleEventCommand(opts, type) {
225
+ try {
226
+ const { schedulePath } = resolveProjectContext(opts);
227
+ const actor = requireNonEmpty("by", opts.by);
228
+ const roster = loadRosterForOpts(opts);
229
+ assertValidActor(actor, roster);
230
+ const event = buildEvent(type, opts);
231
+ if (opts.dryRun) {
232
+ process.stdout.write(`[dry-run] ${JSON.stringify(event, null, 2)}\n`);
233
+ exitWithCode(true);
234
+ return;
235
+ }
236
+ const out = writeEventFile(schedulePath, event);
237
+ process.stdout.write(out + "\n");
238
+ exitWithCode(true);
239
+ }
240
+ catch (error) {
241
+ printCommandError(error, false);
242
+ }
243
+ }
244
+ export async function runLockedEventCommand(opts, action) {
245
+ let lockDir = "";
246
+ try {
247
+ const { schedulePath, executionPath, catalogPath } = resolveProjectContext(opts);
248
+ const actor = requireNonEmpty("by", opts.by);
249
+ const roster = loadRosterForOpts(opts);
250
+ assertValidActor(actor, roster);
251
+ let taskId = typeof opts.task === "string" ? opts.task.trim() : "";
252
+ const allowMultipleDoing = !!opts.allowMultipleDoing;
253
+ const lockTimeoutMs = Number(opts.lockTimeoutMs);
254
+ const lockStaleMs = Number(opts.lockStaleMs);
255
+ lockDir = acquireSchedulerLock(schedulePath, { actor, lockTimeoutMs, lockStaleMs });
256
+ const state = loadValidatedExecState(schedulePath);
257
+ if (!state)
258
+ return;
259
+ if (!taskId && action.type === "complete") {
260
+ const doingTasks = findDoingTasksForActor(state.snapshot, actor);
261
+ if (doingTasks.length === 0) {
262
+ throw new Error(`Actor ${actor} has no doing task to complete.`);
263
+ }
264
+ if (doingTasks.length > 1) {
265
+ throw new Error(`Actor ${actor} has multiple doing tasks: ${doingTasks.join(", ")}. Specify --task.`);
266
+ }
267
+ taskId = doingTasks[0];
268
+ }
269
+ if (!taskId)
270
+ taskId = requireNonEmpty("task", opts.task);
271
+ const resolvedOpts = { ...opts, task: taskId };
272
+ if (action.requireSingleDoing &&
273
+ !ensureActorCanClaimNext(state.snapshot, actor, allowMultipleDoing)) {
274
+ return;
275
+ }
276
+ const check = action.check(state, taskId, actor, resolvedOpts);
277
+ if (!check.ok) {
278
+ process.stdout.write(`Cannot ${action.type} ${taskId}: ${check.reason}\n`);
279
+ exitWithCode(false);
280
+ return;
281
+ }
282
+ const event = buildEvent(action.type, resolvedOpts);
283
+ if (action.type === "claim") {
284
+ const plannedOwner = state.schedule.nodes.get(taskId)?.owner;
285
+ const claimOwner = resolveClaimOwner(resolvedOpts, actor, roster, plannedOwner);
286
+ const cpm = computeCpm(state.schedule, schedulePath);
287
+ writeGeneratedCore(schedulePath, state.events, state.schedule, cpm);
288
+ writeScheduleHashAndDiff(schedulePath, state.schedule);
289
+ writeCpmFiles(schedulePath, cpm, state.snapshot);
290
+ event.meta = {
291
+ ...(event.meta ?? {}),
292
+ claim_owner: claimOwner,
293
+ };
294
+ if (plannedOwner)
295
+ event.meta.planned_owner = plannedOwner;
296
+ if (plannedOwner && claimOwner !== plannedOwner && resolvedOpts.allowOwnerMismatch) {
297
+ event.meta.owner_override = true;
298
+ }
299
+ }
300
+ if (opts.dryRun) {
301
+ process.stdout.write(`[dry-run] ${JSON.stringify(event, null, 2)}\n`);
302
+ if (action.type === "release" && opts.resetWorktree) {
303
+ resetExecWorktreeForTask({
304
+ projectId: resolveProjectId(opts),
305
+ taskId,
306
+ schedulePath,
307
+ executionPath,
308
+ dryRun: true,
309
+ });
310
+ }
311
+ exitWithCode(true);
312
+ return;
313
+ }
314
+ const out = writeEventFile(schedulePath, event);
315
+ if (action.type === "claim") {
316
+ await scaffoldClaimResult({
317
+ schedulePath,
318
+ executionPath,
319
+ catalogPath,
320
+ taskId,
321
+ state,
322
+ projectId: resolveProjectId(opts),
323
+ actor,
324
+ startedAt: new Date().toISOString(),
325
+ });
326
+ }
327
+ // The release event has been persisted (the task is now todo), so a retained exec worktree is
328
+ // stale residue. --reset-worktree discards it eagerly instead of waiting for the next claim to
329
+ // clean it up via discardStaleExecWorktree.
330
+ if (action.type === "release" && opts.resetWorktree) {
331
+ resetExecWorktreeForTask({
332
+ projectId: resolveProjectId(opts),
333
+ taskId,
334
+ schedulePath,
335
+ executionPath,
336
+ dryRun: false,
337
+ });
338
+ }
339
+ process.stdout.write(out + "\n");
340
+ exitWithCode(true);
341
+ }
342
+ catch (error) {
343
+ printCommandError(error);
344
+ }
345
+ finally {
346
+ if (lockDir) {
347
+ try {
348
+ releaseSchedulerLock(lockDir);
349
+ }
350
+ catch { }
351
+ }
352
+ }
353
+ }
354
+ // Discards the exec worktree and branch left behind by a now-released task. A released task is back
355
+ // in todo, so any retained worktree is stale residue. `dryRun` only prints what would be discarded.
356
+ export function resetExecWorktreeForTask(args) {
357
+ const worktreeTaskId = qualifyTaskId(args.projectId, args.taskId);
358
+ if (args.dryRun) {
359
+ process.stdout.write(`[dry-run] reset worktree: discard exec/${worktreeTaskId}\n`);
360
+ return;
361
+ }
362
+ const discarded = discardStaleExecWorktree({
363
+ context: {
364
+ repoRoot: specdojoRootDir(),
365
+ schedulePath: args.schedulePath,
366
+ executionPath: args.executionPath,
367
+ },
368
+ worktreeTaskId,
369
+ // PJR-98G4: repos を宣言した project では、プロダクト側の worktree と exec branch も破棄する。
370
+ products: configuredProductRepos(args.schedulePath),
371
+ });
372
+ process.stdout.write(discarded
373
+ ? `reset worktree: discarded ${discarded}\n`
374
+ : `reset worktree: no worktree or branch for ${worktreeTaskId}\n`);
375
+ }
376
+ // `release --all-blocked`: return every blocked task in the project to todo under a single scheduler
377
+ // lock. Tasks blocked by a different actor are skipped unless --force is given (humans only); each
378
+ // skip is reported with its reason. --reset-worktree discards each released task's stale worktree.
379
+ export async function runReleaseAllBlocked(opts) {
380
+ let lockDir = "";
381
+ try {
382
+ const { schedulePath, executionPath } = resolveProjectContext(opts);
383
+ const actor = requireNonEmpty("by", opts.by);
384
+ const roster = loadRosterForOpts(opts);
385
+ assertValidActor(actor, roster);
386
+ requireNonEmpty("msg", opts.msg);
387
+ if (opts.task) {
388
+ process.stdout.write("Note: --all-blocked ignores --task.\n");
389
+ }
390
+ const lockTimeoutMs = Number(opts.lockTimeoutMs);
391
+ const lockStaleMs = Number(opts.lockStaleMs);
392
+ lockDir = acquireSchedulerLock(schedulePath, { actor, lockTimeoutMs, lockStaleMs });
393
+ const state = loadValidatedExecState(schedulePath);
394
+ if (!state)
395
+ return;
396
+ const projectId = resolveProjectId(opts);
397
+ const blockedTaskIds = Object.entries(state.snapshot.tasks)
398
+ .filter(([, cs]) => cs.state === "blocked")
399
+ .map(([taskId]) => taskId)
400
+ .sort((a, b) => a.localeCompare(b));
401
+ if (blockedTaskIds.length === 0) {
402
+ process.stdout.write("No blocked tasks to release.\n");
403
+ exitWithCode(true);
404
+ return;
405
+ }
406
+ const released = [];
407
+ const skipped = [];
408
+ const override = resolveForceOverride(opts, actor);
409
+ // Releasing one task does not change another task's releasability, so a single snapshot read is
410
+ // sufficient even though the in-memory snapshot is not re-folded after each write.
411
+ for (const taskId of blockedTaskIds) {
412
+ const check = canReleaseTask(state.schedule, state.snapshot, taskId, actor, override);
413
+ if (!check.ok) {
414
+ skipped.push({ taskId, reason: check.reason ?? "not releasable" });
415
+ continue;
416
+ }
417
+ const event = buildEvent("release", { ...opts, task: taskId });
418
+ if (opts.dryRun) {
419
+ process.stdout.write(`[dry-run] ${JSON.stringify(event, null, 2)}\n`);
420
+ if (opts.resetWorktree) {
421
+ resetExecWorktreeForTask({
422
+ projectId,
423
+ taskId,
424
+ schedulePath,
425
+ executionPath,
426
+ dryRun: true,
427
+ });
428
+ }
429
+ released.push(taskId);
430
+ continue;
431
+ }
432
+ const out = writeEventFile(schedulePath, event);
433
+ if (opts.resetWorktree) {
434
+ resetExecWorktreeForTask({ projectId, taskId, schedulePath, executionPath, dryRun: false });
435
+ }
436
+ process.stdout.write(out + "\n");
437
+ released.push(taskId);
438
+ }
439
+ const dryRunSuffix = opts.dryRun ? " (dry-run)" : "";
440
+ process.stdout.write(`\nReleased ${released.length} blocked task(s)${dryRunSuffix}; skipped ${skipped.length}.\n`);
441
+ for (const s of skipped) {
442
+ process.stdout.write(` skip ${s.taskId}: ${s.reason}\n`);
443
+ }
444
+ exitWithCode(true);
445
+ }
446
+ catch (error) {
447
+ printCommandError(error);
448
+ }
449
+ finally {
450
+ if (lockDir) {
451
+ try {
452
+ releaseSchedulerLock(lockDir);
453
+ }
454
+ catch { }
455
+ }
456
+ }
457
+ }