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,184 @@
1
+ import { createHash } from "node:crypto";
2
+ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
3
+ import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
4
+ import { listFilesRecursive } from "./exec-shared.js";
5
+ import { isRecord, parseMarkdown, pipelineContentHash, } from "./grade-core.js";
6
+ import { relativePathFromRoot, repoRelativePath, resolveProject, resolveSafeMarkdownPath, } from "./grade-targets.js";
7
+ import { getProjectExecutionPath, specdojoRootDir } from "./specdojo-config.js";
8
+ function gradePipelineStateDirectory(projectOption, rootDir = specdojoRootDir()) {
9
+ const { project } = resolveProject(projectOption);
10
+ return resolve(rootDir, getProjectExecutionPath(project), "grade", "pipeline");
11
+ }
12
+ function gradePipelineStatePath(documentPath, projectOption, rootDir = specdojoRootDir()) {
13
+ const relativeDocument = relativePathFromRoot(resolve(rootDir, documentPath), rootDir);
14
+ const stem = basename(relativeDocument, extname(relativeDocument)).replace(/[^A-Za-z0-9._-]/g, "-");
15
+ const digest = createHash("sha256").update(relativeDocument).digest("hex").slice(0, 12);
16
+ return join(gradePipelineStateDirectory(projectOption, rootDir), `${stem}-${digest}.json`);
17
+ }
18
+ function parseGradePipelineState(value, path) {
19
+ if (!isRecord(value))
20
+ throw new Error(`${path}: grade pipeline state must be an object`);
21
+ const integer = (key, minimum) => {
22
+ const candidate = value[key];
23
+ if (!Number.isSafeInteger(candidate) || candidate < minimum) {
24
+ throw new Error(`${path}: ${key} must be an integer >= ${minimum}`);
25
+ }
26
+ return candidate;
27
+ };
28
+ const text = (key) => {
29
+ const candidate = value[key];
30
+ if (typeof candidate !== "string" || !candidate.trim()) {
31
+ throw new Error(`${path}: ${key} must be a non-empty string`);
32
+ }
33
+ return candidate;
34
+ };
35
+ const target = value.target;
36
+ if (target !== "kata" && target !== "deliverable") {
37
+ throw new Error(`${path}: target must be kata or deliverable`);
38
+ }
39
+ const stageFailed = value.stage_failed;
40
+ if (stageFailed !== null && (!Number.isSafeInteger(stageFailed) || stageFailed < 1)) {
41
+ throw new Error(`${path}: stage_failed must be null or a positive integer`);
42
+ }
43
+ const state = {
44
+ version: integer("version", 1),
45
+ project_id: text("project_id"),
46
+ target,
47
+ document: text("document"),
48
+ content_hash: text("content_hash"),
49
+ stage_completed: integer("stage_completed", 0),
50
+ stage_failed: stageFailed,
51
+ stage_total: integer("stage_total", 1),
52
+ consecutive_failures: integer("consecutive_failures", 0),
53
+ max_failures: integer("max_failures", 1),
54
+ last_run_id: text("last_run_id"),
55
+ updated_at: text("updated_at"),
56
+ };
57
+ if (state.version !== 1)
58
+ throw new Error(`${path}: unsupported grade pipeline state version`);
59
+ if (!/^[a-f0-9]{64}$/.test(state.content_hash)) {
60
+ throw new Error(`${path}: content_hash must be a SHA-256 hex digest`);
61
+ }
62
+ if (isAbsolute(state.document) ||
63
+ !state.document.startsWith("docs/") ||
64
+ state.document.split("/").includes("..")) {
65
+ throw new Error(`${path}: document must be a repository-relative path below docs/`);
66
+ }
67
+ if (state.stage_completed >= state.stage_total) {
68
+ throw new Error(`${path}: completed pipeline state must be removed`);
69
+ }
70
+ if (state.stage_failed !== null && state.stage_failed !== state.stage_completed + 1) {
71
+ throw new Error(`${path}: stage_failed must immediately follow stage_completed`);
72
+ }
73
+ if ((state.stage_failed === null && state.consecutive_failures !== 0) ||
74
+ (state.stage_failed !== null && state.consecutive_failures < 1)) {
75
+ throw new Error(`${path}: consecutive_failures does not match stage_failed`);
76
+ }
77
+ return state;
78
+ }
79
+ export function loadGradePipelineStates(projectOption, rootDir = specdojoRootDir()) {
80
+ const states = new Map();
81
+ const projectId = resolveProject(projectOption).id;
82
+ for (const path of listFilesRecursive(gradePipelineStateDirectory(projectOption, rootDir))) {
83
+ if (!path.endsWith(".json"))
84
+ continue;
85
+ const state = parseGradePipelineState(JSON.parse(readFileSync(path, "utf8")), relativePathFromRoot(path, rootDir));
86
+ if (state.project_id !== projectId) {
87
+ throw new Error(`${relativePathFromRoot(path, rootDir)}: project_id must be ${projectId}`);
88
+ }
89
+ states.set(state.document, state);
90
+ }
91
+ return states;
92
+ }
93
+ export function currentGradePipelineState(document, path, state, target) {
94
+ if (!state || state.document !== path || (target !== undefined && state.target !== target)) {
95
+ return undefined;
96
+ }
97
+ return state.content_hash === pipelineContentHash(document) ? state : undefined;
98
+ }
99
+ export function isIncompleteGradePipelineState(state) {
100
+ return state !== undefined && state.consecutive_failures < state.max_failures;
101
+ }
102
+ export function readGradePipelineState(opts) {
103
+ const absolute = resolveSafeMarkdownPath(opts.path);
104
+ const relativeDocument = repoRelativePath(absolute);
105
+ const statePath = gradePipelineStatePath(relativeDocument, opts.project);
106
+ if (!existsSync(statePath))
107
+ return undefined;
108
+ const state = parseGradePipelineState(JSON.parse(readFileSync(statePath, "utf8")), repoRelativePath(statePath));
109
+ const projectId = resolveProject(opts.project).id;
110
+ if (state.project_id !== projectId) {
111
+ throw new Error(`${repoRelativePath(statePath)}: project_id must be ${projectId}`);
112
+ }
113
+ const document = parseMarkdown(readFileSync(absolute, "utf8"), relativeDocument);
114
+ return currentGradePipelineState(document, relativeDocument, state, opts.target);
115
+ }
116
+ export function listExhaustedGradePipelineStates(opts) {
117
+ const states = loadGradePipelineStates(opts.project);
118
+ return [...states.values()]
119
+ .filter((state) => {
120
+ if (state.target !== opts.target || state.consecutive_failures < state.max_failures)
121
+ return false;
122
+ const absolute = resolve(specdojoRootDir(), state.document);
123
+ if (!existsSync(absolute))
124
+ return false;
125
+ const document = parseMarkdown(readFileSync(absolute, "utf8"), state.document);
126
+ return currentGradePipelineState(document, state.document, state, opts.target) !== undefined;
127
+ })
128
+ .sort((left, right) => left.document.localeCompare(right.document));
129
+ }
130
+ export function recordGradePipelineStage(opts) {
131
+ const absolute = resolveSafeMarkdownPath(opts.path);
132
+ const relativeDocument = repoRelativePath(absolute);
133
+ const statePath = gradePipelineStatePath(relativeDocument, opts.project);
134
+ if (opts.status === "complete") {
135
+ if (existsSync(statePath))
136
+ unlinkSync(statePath);
137
+ return undefined;
138
+ }
139
+ if (!Number.isSafeInteger(opts.stage) ||
140
+ opts.stage < 1 ||
141
+ !Number.isSafeInteger(opts.stageTotal) ||
142
+ opts.stageTotal < opts.stage ||
143
+ !Number.isSafeInteger(opts.maxFailures) ||
144
+ opts.maxFailures < 1) {
145
+ throw new Error("grade pipeline stage, total, and failure limit are invalid");
146
+ }
147
+ const document = parseMarkdown(readFileSync(absolute, "utf8"), relativeDocument);
148
+ const previous = readGradePipelineState({
149
+ target: opts.target,
150
+ project: opts.project,
151
+ path: relativeDocument,
152
+ });
153
+ const previousCompleted = previous?.stage_completed ?? 0;
154
+ if (opts.stage !== previousCompleted + 1) {
155
+ throw new Error(`grade pipeline stage ${opts.stage} must immediately follow completed stage ${previousCompleted}`);
156
+ }
157
+ const stageCompleted = opts.status === "passed" ? opts.stage : Math.min(previousCompleted, opts.stage - 1);
158
+ if (stageCompleted >= opts.stageTotal) {
159
+ if (existsSync(statePath))
160
+ unlinkSync(statePath);
161
+ return undefined;
162
+ }
163
+ const state = {
164
+ version: 1,
165
+ project_id: resolveProject(opts.project).id,
166
+ target: opts.target,
167
+ document: relativeDocument,
168
+ content_hash: pipelineContentHash(document),
169
+ stage_completed: stageCompleted,
170
+ stage_failed: opts.status === "failed" ? opts.stage : null,
171
+ stage_total: opts.stageTotal,
172
+ consecutive_failures: opts.status === "failed"
173
+ ? previous?.stage_failed === opts.stage
174
+ ? previous.consecutive_failures + 1
175
+ : 1
176
+ : 0,
177
+ max_failures: opts.maxFailures,
178
+ last_run_id: opts.runId,
179
+ updated_at: (opts.now ?? new Date()).toISOString(),
180
+ };
181
+ mkdirSync(dirname(statePath), { recursive: true });
182
+ writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
183
+ return state;
184
+ }