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,371 @@
1
+ import { spawn } from "node:child_process";
2
+ import { createHash, randomUUID } from "node:crypto";
3
+ import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
4
+ import { dirname, join, relative, resolve, sep } from "node:path";
5
+ import { agentProtectedConfigViolation, captureAgentProtectedConfigSnapshot, changedAgentProtectedConfigPaths, } from "./exec-agent-protected-config.js";
6
+ import { agentGitStateViolation, captureAgentGitStateSnapshot, changedAgentGitStateFields, } from "./exec-agent-git-state.js";
7
+ import { ensureDir, safeSlug } from "./exec-shared.js";
8
+ import { gitEnvironment, gitResult, worktreeNameFromTaskId } from "./exec-worktree.js";
9
+ import { getProjectSchedulePath, loadConfig, specdojoRootDir, } from "./specdojo-config.js";
10
+ export const TRIAL_PROMPT_SUFFIX = `
11
+
12
+ ---
13
+
14
+ # Agent comparison trial instructions
15
+
16
+ This is an isolated comparison trial. Edit and validate the artifacts required by the plan, but
17
+ do not update task lifecycle state or create/update the result file. End the final response with
18
+ exactly one machine-readable executor evidence envelope as documented by SpecDojo.
19
+ `;
20
+ export function sha256(value) {
21
+ return createHash("sha256").update(value).digest("hex");
22
+ }
23
+ function normalizePlanPathCandidate(value) {
24
+ const candidate = value
25
+ .trim()
26
+ .replace(/^\.\//u, "")
27
+ .replace(/:\d+(?::\d+)?$/u, "")
28
+ .replace(/[.,;]$/u, "");
29
+ if (!candidate ||
30
+ candidate.startsWith("/") ||
31
+ candidate.includes("://") ||
32
+ /[\s<>{}*?$]/u.test(candidate) ||
33
+ candidate === ".env" ||
34
+ candidate.startsWith("secrets/")) {
35
+ return null;
36
+ }
37
+ if (/^(?:\.specdojo|docs|scripts|src|tests|tools)\//u.test(candidate) ||
38
+ /^(?:lefthook\.yml|package\.json|tsconfig[^/]*\.json|vitest[^/]*\.ts)$/u.test(candidate)) {
39
+ return candidate;
40
+ }
41
+ return null;
42
+ }
43
+ export function extractPlanRepoPaths(plan) {
44
+ const candidates = [];
45
+ for (const match of plan.matchAll(/`([^`\n]+)`/gu))
46
+ candidates.push(match[1]);
47
+ for (const match of plan.matchAll(/\]\(([^)\s]+)(?:\s+[^)]*)?\)/gu))
48
+ candidates.push(match[1]);
49
+ return [
50
+ ...new Set(candidates
51
+ .map(normalizePlanPathCandidate)
52
+ .filter((candidate) => candidate !== null)),
53
+ ].sort();
54
+ }
55
+ function objectExistsAtCommit(repoRoot, commit, path) {
56
+ return gitResult(repoRoot, ["cat-file", "-e", `${commit}:${path}`]).status === 0;
57
+ }
58
+ export function buildTrialBaseValidation(params) {
59
+ const referencedPaths = extractPlanRepoPaths(params.planContent).map((path) => ({
60
+ path,
61
+ exists_at_base: objectExistsAtCommit(params.repoRoot, params.resolvedCommit, path),
62
+ }));
63
+ const missingReferencedPaths = referencedPaths
64
+ .filter((entry) => !entry.exists_at_base)
65
+ .map((entry) => entry.path);
66
+ const planPathExistsAtBase = objectExistsAtCommit(params.repoRoot, params.resolvedCommit, params.planPath);
67
+ const warnings = [];
68
+ const baseIsAncestorOfHead = gitResult(params.repoRoot, [
69
+ "merge-base",
70
+ "--is-ancestor",
71
+ params.resolvedCommit,
72
+ params.headCommit,
73
+ ]).status === 0;
74
+ if (!baseIsAncestorOfHead) {
75
+ warnings.push("The base commit is not an ancestor of HEAD; the current HEAD cannot be used as a linear reference result.");
76
+ }
77
+ if (!planPathExistsAtBase) {
78
+ warnings.push("The plan file is not present at the base commit; the current plan content will still be supplied to every trial.");
79
+ }
80
+ if (missingReferencedPaths.length > 0) {
81
+ warnings.push(`Referenced paths missing at the base commit: ${missingReferencedPaths.join(", ")}`);
82
+ }
83
+ return {
84
+ requested_revision: params.requestedRevision,
85
+ resolved_commit: params.resolvedCommit,
86
+ head_commit_at_start: params.headCommit,
87
+ base_is_ancestor_of_head: baseIsAncestorOfHead,
88
+ defaulted_to_head: params.defaultedToHead,
89
+ plan_path_exists_at_base: planPathExistsAtBase,
90
+ compatible: baseIsAncestorOfHead && missingReferencedPaths.length === 0,
91
+ referenced_paths: referencedPaths,
92
+ missing_referenced_paths: missingReferencedPaths,
93
+ warnings,
94
+ };
95
+ }
96
+ export function classifyReporterFailure(result, reason) {
97
+ if (result === "rate_limit")
98
+ return "rate_limit";
99
+ return reason.startsWith("reporter output invalid after")
100
+ ? "invalid_output"
101
+ : "invocation_failure";
102
+ }
103
+ export function hasValidExecutorEnvelope(stdout) {
104
+ const matches = [
105
+ ...stdout.matchAll(/<specdojo_executor_evidence>\s*([\s\S]*?)\s*<\/specdojo_executor_evidence>/gu),
106
+ ];
107
+ const raw = matches.at(-1)?.[1];
108
+ if (!raw)
109
+ return false;
110
+ try {
111
+ const value = JSON.parse(raw);
112
+ if (!value || typeof value !== "object" || Array.isArray(value))
113
+ return false;
114
+ const report = value;
115
+ return typeof report.final_message === "string" && Array.isArray(report.validations);
116
+ }
117
+ catch {
118
+ return false;
119
+ }
120
+ }
121
+ export function repoRelative(repoRoot, path) {
122
+ const value = relative(repoRoot, path);
123
+ if (!value || value === ".." || value.startsWith(`..${sep}`)) {
124
+ throw new Error(`Path is outside repository root: ${path}`);
125
+ }
126
+ return value.split(sep).join("/");
127
+ }
128
+ export function comparisonDir(executionPath, comparisonId) {
129
+ return join(executionPath, "exec", "trials", safeSlug(comparisonId));
130
+ }
131
+ export function comparisonPath(executionPath, comparisonId) {
132
+ return join(comparisonDir(executionPath, comparisonId), "comparison.json");
133
+ }
134
+ export function writeComparison(path, value) {
135
+ ensureDir(dirname(path));
136
+ const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
137
+ writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, "utf8");
138
+ renameSync(temporary, path);
139
+ }
140
+ export function readComparison(path) {
141
+ if (!existsSync(path))
142
+ throw new Error(`Comparison not found: ${path}`);
143
+ return JSON.parse(readFileSync(path, "utf8"));
144
+ }
145
+ export function configuredWorktreeBase(schedulePath) {
146
+ const { config } = loadConfig();
147
+ if (!config)
148
+ return undefined;
149
+ const rootDir = specdojoRootDir();
150
+ for (const project of Object.values(config.projects)) {
151
+ if (resolve(rootDir, getProjectSchedulePath(project)) === schedulePath) {
152
+ return project.run?.worktree_base;
153
+ }
154
+ }
155
+ return undefined;
156
+ }
157
+ export function parsePositiveInteger(value, flag) {
158
+ if (!value || !/^\d+$/.test(value) || Number(value) < 1) {
159
+ throw new Error(`${flag} must be a positive integer: ${value ?? ""}`);
160
+ }
161
+ return Number(value);
162
+ }
163
+ export function parseRating(value, flag) {
164
+ if (value === undefined)
165
+ return undefined;
166
+ if (!/^[1-5]$/.test(value))
167
+ throw new Error(`${flag} must be an integer from 1 to 5.`);
168
+ return Number(value);
169
+ }
170
+ export function resolveMember(roster, nickname, stageRole) {
171
+ const member = roster?.members.find((candidate) => candidate.type === "agent" && candidate.nickname === nickname);
172
+ if (!member)
173
+ throw new Error(`Agent nickname not found in agent-members.yaml: ${nickname}`);
174
+ if (member.disabled)
175
+ throw new Error(`Agent is disabled in agent-members.yaml: ${nickname}`);
176
+ if ((stageRole === "reporter" && member.stage_role !== "reporter") ||
177
+ (stageRole === "executor" && member.stage_role === "reporter")) {
178
+ throw new Error(`Agent must have stage_role: ${stageRole}: ${nickname}`);
179
+ }
180
+ return member;
181
+ }
182
+ export function spawnAgent(command, prompt, cwd, env) {
183
+ return new Promise((resolveOutcome) => {
184
+ const protectedConfigBefore = captureAgentProtectedConfigSnapshot(cwd);
185
+ const gitStateBefore = captureAgentGitStateSnapshot(cwd);
186
+ const child = spawn(command, { cwd, env, shell: true, stdio: ["pipe", "pipe", "pipe"] });
187
+ let stdout = "";
188
+ let stderr = "";
189
+ let settled = false;
190
+ child.stdin.on("error", () => undefined);
191
+ child.stdout.setEncoding("utf8");
192
+ child.stderr.setEncoding("utf8");
193
+ child.stdout.on("data", (chunk) => {
194
+ stdout += chunk;
195
+ process.stdout.write(chunk);
196
+ });
197
+ child.stderr.on("data", (chunk) => {
198
+ stderr += chunk;
199
+ process.stderr.write(chunk);
200
+ });
201
+ const finish = (outcome) => {
202
+ if (settled)
203
+ return;
204
+ settled = true;
205
+ const protectedChanges = changedAgentProtectedConfigPaths(cwd, protectedConfigBefore);
206
+ if (protectedChanges.length > 0) {
207
+ outcome.stderr += `${agentProtectedConfigViolation(protectedChanges)}\n`;
208
+ outcome.exitCode = 1;
209
+ }
210
+ const gitStateChanges = changedAgentGitStateFields(cwd, gitStateBefore);
211
+ if (gitStateChanges.length > 0) {
212
+ outcome.stderr += `${agentGitStateViolation(gitStateChanges)}\n`;
213
+ outcome.exitCode = 1;
214
+ }
215
+ resolveOutcome(outcome);
216
+ };
217
+ child.once("error", (error) => {
218
+ stderr += `${error.message}\n`;
219
+ finish({ exitCode: null, stdout, stderr });
220
+ });
221
+ child.once("close", (exitCode) => finish({ exitCode, stdout, stderr }));
222
+ child.stdin.end(prompt);
223
+ });
224
+ }
225
+ export function worktreeEnvironment(repoRoot, worktreePath, schedulePath, executionPath) {
226
+ return {
227
+ ...gitEnvironment(),
228
+ SPECDOJO_SCHEDULE_PATH: resolve(worktreePath, repoRelative(repoRoot, schedulePath)),
229
+ SPECDOJO_EXECUTION_PATH: resolve(worktreePath, repoRelative(repoRoot, executionPath)),
230
+ };
231
+ }
232
+ function blankTrial(params) {
233
+ const trialId = safeSlug(params.trialId ?? params.agent);
234
+ const worktreeTaskId = `${params.projectId}:trial:${params.comparisonId}:${trialId}`;
235
+ const name = worktreeNameFromTaskId(worktreeTaskId);
236
+ return {
237
+ trial_id: trialId,
238
+ agent: params.agent,
239
+ reporter_agent: params.reporter ?? null,
240
+ worktree: resolve(params.worktreeBase, name),
241
+ branch: `exec/${name}`,
242
+ status: "pending",
243
+ started_at: null,
244
+ completed_at: null,
245
+ duration_ms: null,
246
+ executor: {
247
+ exit_code: null,
248
+ attempts: 0,
249
+ duration_ms: null,
250
+ structured_output: false,
251
+ validations_reported: 0,
252
+ validations_passed: 0,
253
+ validations_failed: 0,
254
+ validations_not_run: 0,
255
+ validations_requires_human: 0,
256
+ files_changed: 0,
257
+ evidence_ref: null,
258
+ final_message: "",
259
+ validations: [],
260
+ changes: [],
261
+ diff_summary: "",
262
+ },
263
+ parent_validation: {
264
+ configured_ids: [...(params.parentValidationIds ?? [])],
265
+ status: params.parentValidationIds?.length ? "not_run" : "not_configured",
266
+ duration_ms: null,
267
+ validations_passed: 0,
268
+ validations_failed: 0,
269
+ validations_not_run: 0,
270
+ },
271
+ reporter: {
272
+ status: "not_run",
273
+ structured_output: false,
274
+ format_attempts: 0,
275
+ format_retries: 0,
276
+ outcome: null,
277
+ output: null,
278
+ failure_category: null,
279
+ failure_reason: "",
280
+ },
281
+ subjective: {
282
+ judgment_quality: null,
283
+ writing_quality: null,
284
+ scope_adherence: null,
285
+ notes: "",
286
+ },
287
+ };
288
+ }
289
+ export function buildComparisonRecord(params) {
290
+ const reporterMode = params.pairs ? "paired" : params.reporter ? "shared" : "none";
291
+ const definitions = params.pairs ??
292
+ (params.agents ?? []).map((agent) => ({ executor: agent, reporter: params.reporter }));
293
+ const trialIds = definitions.map(({ executor, reporter }) => safeSlug(reporterMode === "paired" ? `${executor}-${reporter}` : executor));
294
+ if (new Set(trialIds).size !== trialIds.length) {
295
+ throw new Error("Trial executor/reporter selections must produce distinct trial ids.");
296
+ }
297
+ const baseValidation = params.baseValidation ??
298
+ {
299
+ requested_revision: "HEAD",
300
+ resolved_commit: params.baseCommit,
301
+ head_commit_at_start: params.baseCommit,
302
+ base_is_ancestor_of_head: true,
303
+ defaulted_to_head: true,
304
+ plan_path_exists_at_base: true,
305
+ compatible: true,
306
+ referenced_paths: [],
307
+ missing_referenced_paths: [],
308
+ warnings: [],
309
+ };
310
+ return {
311
+ schema_version: 1,
312
+ comparison_id: params.comparisonId,
313
+ project_id: params.projectId,
314
+ task_id: params.taskId,
315
+ status: "active",
316
+ created_at: params.createdAt,
317
+ completed_at: null,
318
+ base_commit: params.baseCommit,
319
+ base: baseValidation,
320
+ reporter_mode: reporterMode,
321
+ plan: {
322
+ path: params.planPath,
323
+ sha256: sha256(params.planContent),
324
+ prompt_sha256: sha256(params.prompt),
325
+ },
326
+ selected_trial_id: null,
327
+ trials: definitions.map(({ executor, reporter }, index) => blankTrial({
328
+ projectId: params.projectId,
329
+ comparisonId: params.comparisonId,
330
+ agent: executor,
331
+ trialId: trialIds[index],
332
+ reporter,
333
+ worktreeBase: params.worktreeBase,
334
+ parentValidationIds: params.parentValidationIds,
335
+ })),
336
+ agent_selection: {
337
+ policy: "manual",
338
+ target: "agent-members.yaml",
339
+ rationale: "A single comparison does not automatically change agent assignment. A human reviews objective and subjective results, then updates agent-members.yaml priority/capabilities when repeated evidence supports the change.",
340
+ },
341
+ };
342
+ }
343
+ export function updateObjectiveMetrics(trial, evidence, structuredOutput) {
344
+ trial.executor.structured_output = structuredOutput;
345
+ trial.executor.files_changed = evidence.diff_summary.files_changed;
346
+ trial.executor.final_message = evidence.final_message;
347
+ trial.executor.validations = evidence.validations;
348
+ trial.executor.changes = evidence.changes;
349
+ trial.executor.diff_summary = evidence.diff_summary.summary;
350
+ const executorValidations = evidence.validations.filter((validation) => validation.source !== "runner");
351
+ trial.executor.validations_reported = executorValidations.length;
352
+ trial.executor.validations_passed = 0;
353
+ trial.executor.validations_failed = 0;
354
+ trial.executor.validations_not_run = 0;
355
+ trial.executor.validations_requires_human = 0;
356
+ for (const validation of executorValidations) {
357
+ if (validation.status === "passed")
358
+ trial.executor.validations_passed++;
359
+ else if (validation.status === "failed")
360
+ trial.executor.validations_failed++;
361
+ else if (validation.status === "not_run")
362
+ trial.executor.validations_not_run++;
363
+ else if (validation.status === "requires_human") {
364
+ trial.executor.validations_requires_human++;
365
+ }
366
+ }
367
+ const parentValidations = evidence.validations.filter((validation) => validation.source === "runner");
368
+ trial.parent_validation.validations_passed = parentValidations.filter((validation) => validation.status === "passed").length;
369
+ trial.parent_validation.validations_failed = parentValidations.filter((validation) => validation.status === "failed").length;
370
+ trial.parent_validation.validations_not_run = parentValidations.filter((validation) => validation.status === "not_run").length;
371
+ }