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
@@ -1,21 +1,19 @@
1
- import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
1
+ import { existsSync, readFileSync } from "node:fs";
2
2
  import { basename, join, relative, resolve } from "node:path";
3
- import { load } from "js-yaml";
4
- import { DEFAULT_PROJECT_CONTEXT, specdojoRootDir } from "./specdojo-config.js";
5
- import { kataDirsForKinds, resolveDeliverableSchemaRef, resolveIncludedRulebooks, resolveKataRefs, } from "./kata.js";
6
- import { resolveBasePath, resolveDeliverablePath } from "./catalog-paths.js";
7
- import { isDctPlanFileName } from "./catalog-plan.js";
8
- import { buildSpecdojoFrontmatter, readSpecdojoNamespace } from "./frontmatter-namespace.js";
9
- import { formatMarkdownFile } from "./exec-format.js";
10
- import { qualifyPracticeId, SPECDOJO_PRACTICE_AUTHORITY } from "./practice-id.js";
11
- import { resolveViewpointsDoc, viewpointAppliesToDocument } from "./review-plan.js";
12
- import { expandTemplate, listFilesRecursive, nowUtcIsoSeconds, randomHex, tsForFilenameUtc, } from "./exec-shared.js";
13
- import { gradeFindingDisplayMessage, gradeResultPathForDocument, readGradeResultForDocument, } from "./grade-result.js";
14
- import { lookupDocIndex } from "./doc-index.js";
15
- import { resolveSpecdojoPath, resolveSpecdojoPathIfExists } from "./template-resolution.js";
16
- import { renderReviewGradeSummary, reviewGradeFreshness } from "./review-grade.js";
17
- export const MISSING = "_MISSING_";
18
- function execDocId(projectId, prefix, localBase) {
3
+ import { load } from "../shared/yaml.js";
4
+ import { specdojoRootDir } from "../shared/specdojo-config.js";
5
+ import { kataDirsForKinds, resolveIncludedRulebooks, resolveKataRefs } from "../kata/kata.js";
6
+ import { resolveBasePath, resolveDeliverablePath } from "../catalog/paths.js";
7
+ import { isDctPlanFileName } from "../catalog/plan.js";
8
+ import { buildSpecdojoFrontmatter, readSpecdojoNamespace } from "../docs/frontmatter-namespace.js";
9
+ import { qualifyPracticeId, SPECDOJO_PRACTICE_AUTHORITY } from "../shared/practice-id.js";
10
+ import { MISSING } from "../shared/plan-templates.js";
11
+ export { MISSING, execTemplatePath, execTemplatesDir, injectCommonConventions, loadPlanTemplate, } from "../shared/plan-templates.js";
12
+ import { resolveViewpointsDoc, viewpointAppliesToDocument } from "../review/plan.js";
13
+ import { listFilesRecursive, nowUtcIsoSeconds, randomHex, tsForFilenameUtc } from "./shared.js";
14
+ import { gradeFindingDisplayMessage, gradeResultPathForDocument, readGradeResultForDocument, } from "../shared/grade-result.js";
15
+ import { renderReviewGradeSummary, reviewGradeFreshness } from "../review/grade.js";
16
+ export function execDocId(projectId, prefix, localBase) {
19
17
  const localId = `${prefix}-${localBase.toLowerCase()}`;
20
18
  return projectId ? `${projectId}:${localId}` : localId;
21
19
  }
@@ -50,7 +48,7 @@ function searchSections(sections, parentBase, localId) {
50
48
  }
51
49
  return null;
52
50
  }
53
- function findDeliverableInfo(catalogPath, localId) {
51
+ export function findDeliverableInfo(catalogPath, localId) {
54
52
  if (!catalogPath || !existsSync(catalogPath))
55
53
  return null;
56
54
  // Catalog scans walk subdirectories, so agent judgment plans (plans/dct-plan-*.yaml)
@@ -75,7 +73,7 @@ function findDeliverableInfo(catalogPath, localId) {
75
73
  }
76
74
  return null;
77
75
  }
78
- function loadCatalogDocs(catalogPath) {
76
+ export function loadCatalogDocs(catalogPath) {
79
77
  if (!catalogPath || !existsSync(catalogPath))
80
78
  return [];
81
79
  // Catalog scans walk subdirectories, so agent judgment plans (plans/dct-plan-*.yaml)
@@ -97,6 +95,60 @@ function loadCatalogDocs(catalogPath) {
97
95
  }
98
96
  return docs;
99
97
  }
98
+ function resolvedDeliverablesInCatalog(catalogPath) {
99
+ const deliverables = [];
100
+ const visit = (sections, parentBase, domain) => {
101
+ for (const section of sections) {
102
+ const sectionBase = resolveBasePath(parentBase, section.base_path);
103
+ for (const item of section.deliverables ?? []) {
104
+ deliverables.push({
105
+ domain,
106
+ localId: item.local_id,
107
+ slug: item.local_id,
108
+ info: {
109
+ deliverable: item,
110
+ resolvedPath: resolveDeliverablePath(sectionBase, item.path),
111
+ },
112
+ });
113
+ }
114
+ visit(section.groups ?? [], sectionBase, domain);
115
+ }
116
+ };
117
+ for (const doc of loadCatalogDocs(catalogPath)) {
118
+ visit(doc.groups, resolveBasePath("", doc.base_path), doc.domain);
119
+ }
120
+ return deliverables;
121
+ }
122
+ // Register targets use document IDs rather than schedule local_ids. Resolve the document ID
123
+ // back to its catalog entry so register-originated approach plans can share schedule rendering.
124
+ export function resolveDeliverableByDocId(catalogPath, projectId, targetId) {
125
+ const matches = resolvedDeliverablesInCatalog(catalogPath).filter((target) => {
126
+ const docId = deliverableDocId(projectId, target.info.deliverable.local_id, target.info.resolvedPath);
127
+ return (targetId === docId ||
128
+ targetId === target.localId ||
129
+ targetId === qualifiedDocId(projectId, target.localId));
130
+ });
131
+ if (matches.length === 0) {
132
+ throw new Error(`catalog deliverable target not found for document id: ${targetId}`);
133
+ }
134
+ if (matches.length > 1) {
135
+ throw new Error(`ambiguous catalog deliverable target for document id ${targetId}: ${matches
136
+ .map((match) => match.localId)
137
+ .join(", ")}`);
138
+ }
139
+ return matches[0];
140
+ }
141
+ // A kata may be declared by zero, one, or several deliverables. Only a unique declaration is
142
+ // used as the maintenance plan's evidence context; otherwise the explicitly targeted kata remains
143
+ // executable without selecting an arbitrary deliverable.
144
+ export function findUniqueDeliverableForKataTarget(catalogPath, targetId, kind) {
145
+ const matches = resolvedDeliverablesInCatalog(catalogPath).filter((target) => {
146
+ const refs = resolveKataRefs(target.info.deliverable.rulebook, target.info.deliverable.kind);
147
+ const refPath = refs[kind];
148
+ return refPath !== MISSING && refDocIdFromPath(refPath) === targetId;
149
+ });
150
+ return matches.length === 1 ? matches[0].info : null;
151
+ }
100
152
  // Resolve a `--deliverable` identifier (a bare `local_id`) to a catalog deliverable.
101
153
  // `local_id` is unique project-wide (catalog validate warns otherwise); an ambiguous
102
154
  // match is an error rather than a silent first match.
@@ -120,13 +172,13 @@ export function resolveDeliverableTarget(catalogPath, value) {
120
172
  }
121
173
  return matches[0];
122
174
  }
123
- function loadViewpoints(viewpointsPath) {
175
+ export function loadViewpoints(viewpointsPath) {
124
176
  if (!viewpointsPath || !existsSync(viewpointsPath))
125
177
  return new Map();
126
178
  const doc = resolveViewpointsDoc(viewpointsPath);
127
179
  return new Map((doc.viewpoints ?? []).map((vp) => [vp.id, vp]));
128
180
  }
129
- function loadRoles(rolesPath) {
181
+ export function loadRoles(rolesPath) {
130
182
  if (!rolesPath || !existsSync(rolesPath))
131
183
  return new Map();
132
184
  try {
@@ -140,13 +192,13 @@ function loadRoles(rolesPath) {
140
192
  // Canonical repo-root-relative path: POSIX separators, no leading slash. Agents and
141
193
  // tools resolve it from the run CWD (repo root for in-place, worktree root otherwise),
142
194
  // so a leading slash (filesystem-absolute) must not be emitted.
143
- function repoRelativePath(absPath) {
195
+ export function repoRelativePath(absPath) {
144
196
  return relative(specdojoRootDir(), absPath).replace(/\\/g, "/");
145
197
  }
146
198
  // ---------------------------------------------------------------------------
147
199
  // Markdown builders
148
200
  // ---------------------------------------------------------------------------
149
- function frontmatter(meta) {
201
+ export function frontmatter(meta) {
150
202
  const inner = [
151
203
  `id: ${meta.id}`,
152
204
  `type: ${meta.type}`,
@@ -173,118 +225,18 @@ function frontmatter(meta) {
173
225
  return buildSpecdojoFrontmatter(inner);
174
226
  }
175
227
  // ---------------------------------------------------------------------------
176
- // Template-based generation (edit-plan / review-plan テンプレートの展開)
177
- // ---------------------------------------------------------------------------
178
- // Shared conventions (link notation など) appended to every generated plan. The plan is the
179
- // only context guaranteed to reach the executing agent regardless of tool (it is piped via
180
- // stdin), so cross-tool rules must travel with the plan rather than tool-specific instruction
181
- // files. Kept as a single fragment to avoid duplicating the rule across every plan template.
182
- const COMMON_CONVENTIONS_TEMPLATE = "xep-common-conventions-template.md";
183
- export function execTemplatesDir() {
184
- return resolveSpecdojoPath("docs/ja/specdojo/exec-templates");
185
- }
186
- export function execTemplatePath(fileName) {
187
- return resolveSpecdojoPath(`docs/ja/specdojo/exec-templates/${fileName}`);
188
- }
189
- function templatePrefix(mode) {
190
- return mode === "review" ? "xrp" : "xep";
191
- }
192
- function standardTemplateFileName(mode) {
193
- return `${templatePrefix(mode)}-template.md`;
194
- }
195
- function approachTemplateFileName(mode, approach) {
196
- return `${templatePrefix(mode)}-${approach}-template.md`;
197
- }
198
- // Selects <prefix>-<approach>-template.md when it exists, falling back
199
- // to the standard <prefix>-template.md. Any missing variant falls through to the
200
- // next candidate so a plan is always produced.
201
- function resolvePlanTemplatePath(mode, approach) {
202
- if (approach) {
203
- const candidatePath = resolveSpecdojoPathIfExists(`docs/ja/specdojo/exec-templates/${approachTemplateFileName(mode, approach)}`);
204
- if (candidatePath)
205
- return candidatePath;
206
- }
207
- return execTemplatePath(standardTemplateFileName(mode));
208
- }
209
- function readTemplate(templatePath, cache) {
210
- const cached = cache.get(templatePath);
211
- if (cached !== undefined)
212
- return cached;
213
- if (!existsSync(templatePath)) {
214
- throw new Error(`Template not found: ${templatePath}`);
215
- }
216
- const content = readFileSync(templatePath, "utf8");
217
- cache.set(templatePath, content);
218
- return content;
219
- }
220
- function loadPlanTemplate(mode, approach, cache) {
221
- return readTemplate(resolvePlanTemplatePath(mode, approach), cache);
222
- }
223
- // Marker a plan template places to control where the shared conventions fragment lands.
224
- const COMMON_CONVENTIONS_PLACEHOLDER = "_COMMON_CONVENTIONS_";
225
- // Lines delimiting the review-only block of the conventions fragment (review の判断手順). The
226
- // block is kept, without the marker lines, in review plans and dropped from every other plan.
227
- const REVIEW_ONLY_START = "<!-- review-only:start -->";
228
- const REVIEW_ONLY_END = "<!-- review-only:end -->";
229
- function selectReviewOnlyBlock(conventions, isReview) {
230
- const kept = [];
231
- let inside = false;
232
- for (const line of conventions.split("\n")) {
233
- const marker = line.trim();
234
- if (marker === REVIEW_ONLY_START) {
235
- inside = true;
236
- continue;
237
- }
238
- if (marker === REVIEW_ONLY_END) {
239
- inside = false;
240
- continue;
241
- }
242
- if (!inside || isReview)
243
- kept.push(line);
244
- }
245
- return kept
246
- .join("\n")
247
- .replace(/\n{3,}/g, "\n\n")
248
- .trimEnd();
249
- }
250
- // Placeholder in the conventions fragment for the resolved schema path. The agent cannot derive
251
- // the schema path on its own (it would have to hunt for it and risks burning its turn before
252
- // filling the result), so the generator resolves it deterministically and bakes it in here.
253
- const SCHEMA_REF_PLACEHOLDER = "_SCHEMA_REF_";
254
- // Injects the shared conventions fragment into a built plan body so every generated plan carries
255
- // the same rules (e.g. link notation) in its own text, independent of the executing tool. A
256
- // template controls placement via the COMMON_CONVENTIONS_PLACEHOLDER marker; templates without the
257
- // marker get the block appended so the rules are never silently dropped.
258
- // schemaRef is the resolved schema path: when MISSING (non-yaml deliverable or no schema), the
259
- // schema-validation bullet is dropped so the plan never asks for a check it cannot specify.
260
- // mode selects whether the review-only block (review の判断手順) is kept; it defaults to edit so
261
- // register / job plans never carry review instructions.
262
- export function injectCommonConventions(body, schemaRef, cache, mode = "edit") {
263
- let conventions = selectReviewOnlyBlock(readTemplate(execTemplatePath(COMMON_CONVENTIONS_TEMPLATE), cache), mode === "review");
264
- conventions =
265
- schemaRef === MISSING
266
- ? conventions
267
- .split("\n")
268
- .filter((line) => !line.includes(SCHEMA_REF_PLACEHOLDER))
269
- .join("\n")
270
- : conventions.split(SCHEMA_REF_PLACEHOLDER).join(schemaRef);
271
- if (body.includes(COMMON_CONVENTIONS_PLACEHOLDER)) {
272
- return body.split(COMMON_CONVENTIONS_PLACEHOLDER).join(conventions);
273
- }
274
- return `${body.trimEnd()}\n\n${conventions}\n`;
275
- }
276
- function phaseDescriptionText(task) {
228
+ export function phaseDescriptionText(task) {
277
229
  if (task.description)
278
230
  return task.description.trimEnd();
279
231
  return task.name ?? task.id;
280
232
  }
281
- function deliverablePath(deliverable) {
233
+ export function deliverablePath(deliverable) {
282
234
  return deliverable?.resolvedPath ?? MISSING;
283
235
  }
284
- function deliverableName(deliverable) {
236
+ export function deliverableName(deliverable) {
285
237
  return deliverable?.deliverable.name ?? MISSING;
286
238
  }
287
- function gradeFindingsText(projectId, targetPath) {
239
+ export function gradeFindingsText(projectId, targetPath) {
288
240
  if (!targetPath || targetPath === MISSING || !existsSync(join(specdojoRootDir(), targetPath))) {
289
241
  return "- なし";
290
242
  }
@@ -300,7 +252,7 @@ function gradeFindingsText(projectId, targetPath) {
300
252
  return "- なし";
301
253
  }
302
254
  }
303
- function gradeFindingTargetPath(approach, deliverable, refs) {
255
+ export function gradeFindingTargetPath(approach, deliverable, refs) {
304
256
  if (approach === "rulebook-maintenance")
305
257
  return refs.rulebook;
306
258
  if (approach === "recipe-maintenance")
@@ -312,7 +264,7 @@ function gradeFindingTargetPath(approach, deliverable, refs) {
312
264
  return deliverablePath(deliverable);
313
265
  }
314
266
  // grade の --target。実践の型メンテナンス系は実践の型そのものを評価対象にする。
315
- function gradeTargetKind(approach) {
267
+ export function gradeTargetKind(approach) {
316
268
  return approach === "rulebook-maintenance" ||
317
269
  approach === "recipe-maintenance" ||
318
270
  approach === "sample-maintenance" ||
@@ -331,7 +283,7 @@ export function reviewGradeSubject(catalogPath, task) {
331
283
  return { path, target: gradeTargetKind(task.approach) };
332
284
  }
333
285
  // review plan に提示する評価結果。runner の grade 実行結果があれば併記する。
334
- function reviewGradeSummaryText(projectId, subjectPath, outcome) {
286
+ export function reviewGradeSummaryText(projectId, subjectPath, outcome) {
335
287
  return renderReviewGradeSummary(reviewGradeFreshness({
336
288
  subjectPath: subjectPath === MISSING ? "" : subjectPath,
337
289
  projectId,
@@ -340,7 +292,7 @@ function reviewGradeSummaryText(projectId, subjectPath, outcome) {
340
292
  }
341
293
  // 評価対象に対応する評価結果サイドカーのリポジトリ相対パス。評価対象が未作成、または
342
294
  // frontmatter の id を解決できない場合は MISSING を返す(サイドカーの有無は問わない)。
343
- function gradeResultRef(projectId, subjectPath) {
295
+ export function gradeResultRef(projectId, subjectPath) {
344
296
  if (!subjectPath || subjectPath === MISSING)
345
297
  return MISSING;
346
298
  if (!existsSync(join(specdojoRootDir(), subjectPath)))
@@ -355,18 +307,18 @@ function gradeResultRef(projectId, subjectPath) {
355
307
  // plan に表示する実践の型の状態。宣言からパスを解決できたがファイルが無い場合と、
356
308
  // 宣言不足・対象外などでパス自体を解決できない場合を分ける。これにより executor は
357
309
  // 既存文書の編集、宣言済みパスへの新規作成、前提確認が必要な状態を推測せず判別できる。
358
- function kataRefState(refPath) {
310
+ export function kataRefState(refPath) {
359
311
  if (refPath === MISSING)
360
312
  return "unresolved";
361
313
  return existsSync(join(specdojoRootDir(), refPath)) ? "existing" : "missing";
362
314
  }
363
315
  // 対象成果物の depends_on を、依存先 doc の [[id]] 参照の入れ子リストで提示する。
364
316
  // id は依存先の frontmatter、未作成なら配置規約から解決する。agent へ plan を渡すときに
365
- // expandPromptRefs(src/exec-run.ts, format:'path')が
317
+ // expandPromptRefs(src/exec/run/agent.ts, format:'path')が
366
318
  // この [[id]] を doc-index 経由でリポジトリ相対パスへ展開し、agent が先行成果物を直接開ける。
367
319
  // テンプレート側はラベル直後にこの値を差し込むため、件数 0・成果物未解決時は先頭スペース付きの
368
320
  // インライン値、依存ありの場合は改行始まりの入れ子リストを返す。
369
- function deliverableDependsOn(deliverable, projectId, catalogPath) {
321
+ export function deliverableDependsOn(deliverable, projectId, catalogPath) {
370
322
  if (!deliverable)
371
323
  return ` ${MISSING}`;
372
324
  const deps = deliverable.deliverable.depends_on ?? [];
@@ -390,7 +342,7 @@ const PROJECT_CONTEXT_EXCLUDED_APPROACHES = new Set([
390
342
  // Project context is project-level guidance, not an ordering/evidence edge. It is rendered only
391
343
  // for deliverable edit/review work, separately from depends_on, and is deliberately omitted for
392
344
  // maintenance/finalize work and when the target itself is the configured context document.
393
- function projectContextSection(refs, deliverable, approach, projectId) {
345
+ export function projectContextSection(refs, deliverable, approach, projectId) {
394
346
  if (!deliverable || (approach && PROJECT_CONTEXT_EXCLUDED_APPROACHES.has(approach)))
395
347
  return "";
396
348
  const targetId = deliverableDocId(projectId, deliverable.deliverable.local_id, deliverable.resolvedPath);
@@ -413,10 +365,10 @@ function projectContextSection(refs, deliverable, approach, projectId) {
413
365
  "プロジェクトレベルの Why は判断軸として参照し、全文を成果物へ再掲しない。対象成果物の責務に必要な結論・影響だけを反映する。",
414
366
  ].join("\n");
415
367
  }
416
- function deliverableOverview(deliverable) {
368
+ export function deliverableOverview(deliverable) {
417
369
  return deliverable?.deliverable.overview ?? MISSING;
418
370
  }
419
- function implementationEvidence(deliverable) {
371
+ export function implementationEvidence(deliverable) {
420
372
  const refs = deliverable?.deliverable.evidence_refs ?? [];
421
373
  if (refs.length === 0)
422
374
  return MISSING;
@@ -427,7 +379,7 @@ function implementationEvidence(deliverable) {
427
379
  // 成立させる範囲にとどめる(各ロールの内容を作り込まない)。下流の適合性検証や観点別の自己
428
380
  // レビューは edit plan では行わず、多観点検証は独立した review plan に委ねる。
429
381
  // owner が done_criteria に現れない場合は分割せず全件を素の箇条書きにフォールバックする。
430
- function doneCriteriaGoals(criteria, owner) {
382
+ export function doneCriteriaGoals(criteria, owner) {
431
383
  if (criteria.length === 0)
432
384
  return MISSING;
433
385
  const ownerCriteria = owner ? criteria.filter((c) => c.roles.includes(owner)) : [];
@@ -450,14 +402,14 @@ function doneCriteriaGoals(criteria, owner) {
450
402
  // done_criteria を人間の最終確認用チェックリストに整形する。owner/下流の分割はせず、
451
403
  // 各項目を `- [ ] <text>` の素のチェック項目にする(human finalize は多観点の作り込みでは
452
404
  // なく、完成版が done_criteria を満たすかの確認が目的のため)。criteria が空なら MISSING。
453
- function doneCriteriaChecklist(criteria) {
405
+ export function doneCriteriaChecklist(criteria) {
454
406
  if (criteria.length === 0)
455
407
  return MISSING;
456
408
  return criteria.map((c) => `- [ ] ${c.text}`).join("\n");
457
409
  }
458
410
  // done_criteria を plan 提示用の素の箇条書きに整形する。チェックの記録は result 側の
459
411
  // チェックリストで行うため、plan では「何を確認するか」の列挙にとどめる。
460
- function doneCriteriaItems(criteria) {
412
+ export function doneCriteriaItems(criteria) {
461
413
  if (criteria.length === 0)
462
414
  return MISSING;
463
415
  return criteria.map((c) => `- ${c.text}`).join("\n");
@@ -465,7 +417,7 @@ function doneCriteriaItems(criteria) {
465
417
  // 主 rulebook が include する rulebook を plan へ注入する表記に整形する。
466
418
  // 併せて適用する rulebook(記法など)を backtick 付きパスのカンマ区切りで示す。
467
419
  // include が無い場合は他の参照と同様に MISSING を返す。
468
- function rulebookIncludesText(rulebookId, targetKind) {
420
+ export function rulebookIncludesText(rulebookId, targetKind) {
469
421
  if (targetKind === "generated")
470
422
  return MISSING;
471
423
  const paths = resolveIncludedRulebooks(rulebookId);
@@ -523,7 +475,7 @@ export function deliverableDocId(projectId, localId, resolvedPath) {
523
475
  // 取得できるようにする。解決できない実践の型(_MISSING_)は含めない。
524
476
  // targets は frontmatter の必須項目のため、catalog で成果物を解決できない場合も
525
477
  // fallbackLocalId から成果物の doc id だけは組み立てる。
526
- function targetDocIds(projectId, deliverable, approach, fallbackLocalId) {
478
+ export function targetDocIds(projectId, deliverable, approach, fallbackLocalId) {
527
479
  if (!deliverable) {
528
480
  return fallbackLocalId ? [qualifiedDocId(projectId, fallbackLocalId)] : [];
529
481
  }
@@ -541,7 +493,7 @@ function targetDocIds(projectId, deliverable, approach, fallbackLocalId) {
541
493
  }
542
494
  return ids;
543
495
  }
544
- function targetDocIdsForTask(projectId, task, deliverable, crossDeliverables) {
496
+ export function targetDocIdsForTask(projectId, task, deliverable, crossDeliverables) {
545
497
  if (task.target_local_ids && task.target_local_ids.length > 0) {
546
498
  return [...new Set(task.target_local_ids)].map((localId) => {
547
499
  const info = crossDeliverables.get(localId);
@@ -584,7 +536,7 @@ export function targetDocIdsForScheduledTask(catalogPath, task, projectId) {
584
536
  }
585
537
  return targetDocIdsForDeliverable(catalogPath, task.local_id, projectId, task.approach);
586
538
  }
587
- function crossDeliverableTargetDetails(projectId, localIds, deliverables, catalogPath) {
539
+ export function crossDeliverableTargetDetails(projectId, localIds, deliverables, catalogPath) {
588
540
  const lines = [];
589
541
  for (const localId of localIds) {
590
542
  const info = deliverables.get(localId);
@@ -611,7 +563,7 @@ function crossDeliverableTargetDetails(projectId, localIds, deliverables, catalo
611
563
  }
612
564
  // review plan の完了条件表の行。review は観点ごとに評価せず、done_criteria をタスクの
613
565
  // 完了条件として照合するため、ID は DC-NNN とする。
614
- function reviewDoneCriteriaRows(criteria) {
566
+ export function reviewDoneCriteriaRows(criteria) {
615
567
  if (criteria.length === 0)
616
568
  return MISSING;
617
569
  const lines = [];
@@ -693,326 +645,3 @@ export function ownerRoleFields(owner, roleMap, vpMap, rulebook) {
693
645
  }
694
646
  // edit plan は観点別の自己レビューを行わない。done_criteria は §3 の owner 視点とは別に
695
647
  // 「完了の狙い」として素の箇条書きで提示し、多観点検証は独立した review plan に委ねる。
696
- function buildEditPlanMarkdown(template, task, deliverable, roleMap, vpMap, projectId, catalogPath, projectContext, resultRef, stem, crossDeliverables = new Map()) {
697
- const cpm = task.cpm;
698
- const onCriticalPath = cpm !== undefined && cpm.slack === 0;
699
- const targets = targetDocIdsForTask(projectId, task, deliverable, crossDeliverables);
700
- const meta = {
701
- id: execDocId(projectId, "xep", stem),
702
- type: "exec-plan",
703
- rulebook: "none",
704
- task_id: task.id,
705
- ...(task.name ? { name: task.name } : {}),
706
- mode: "edit",
707
- status: "ready",
708
- project_id: projectId,
709
- ...(task.owner ? { owner: task.owner } : {}),
710
- ...(onCriticalPath ? { on_critical_path: true } : {}),
711
- ...(task.approach ? { approach: task.approach } : {}),
712
- ...(targets.length > 0 ? { targets } : {}),
713
- };
714
- const criteria = deliverable?.deliverable.done_criteria ?? [];
715
- const ownerRole = ownerRoleFields(task.owner, roleMap, vpMap, deliverable?.deliverable.rulebook);
716
- const refs = resolveKataRefs(deliverable?.deliverable.rulebook, deliverable?.deliverable.kind);
717
- const values = {
718
- _FRONTMATTER_: frontmatter(meta),
719
- _TASK_ID_: task.id,
720
- _PHASE_DESCRIPTION_: phaseDescriptionText(task),
721
- _DELIVERABLE_NAME_: deliverableName(deliverable),
722
- _DELIVERABLE_DEPENDS_ON_: deliverableDependsOn(deliverable, projectId, catalogPath),
723
- _PROJECT_CONTEXT_: projectContextSection(projectContext, deliverable, task.approach, projectId),
724
- _DELIVERABLE_OVERVIEW_: deliverableOverview(deliverable),
725
- _IMPLEMENTATION_EVIDENCE_: implementationEvidence(deliverable),
726
- _DELIVERABLE_PATH_: deliverablePath(deliverable),
727
- _RESULT_REF_: resultRef,
728
- _RULEBOOK_REF_: refs.rulebook,
729
- _RULEBOOK_STATE_: kataRefState(refs.rulebook),
730
- _RULEBOOK_INCLUDES_: rulebookIncludesText(deliverable?.deliverable.rulebook, deliverable?.deliverable.kind),
731
- _RECIPE_REF_: refs.recipe,
732
- _RECIPE_STATE_: kataRefState(refs.recipe),
733
- _SAMPLE_REF_: refs.sample,
734
- _SAMPLE_STATE_: kataRefState(refs.sample),
735
- _TEMPLATE_REF_: refs.template,
736
- _TEMPLATE_STATE_: kataRefState(refs.template),
737
- _OWNER_ROLE_LABEL_: ownerRole.label,
738
- _OWNER_ROLE_NOTE_: ownerRole.note,
739
- _OWNER_ROLE_VIEWPOINTS_: ownerRole.viewpoints,
740
- _DONE_CRITERIA_GOALS_: doneCriteriaGoals(criteria, task.owner),
741
- _DONE_CRITERIA_CHECKLIST_: doneCriteriaChecklist(criteria),
742
- _DONE_CRITERIA_ITEMS_: doneCriteriaItems(criteria),
743
- _GRADE_FINDINGS_: gradeFindingsText(projectId, gradeFindingTargetPath(task.approach, deliverable, refs)),
744
- _TARGET_DELIVERABLES_: crossDeliverableTargetDetails(projectId, task.target_local_ids ?? [], crossDeliverables, catalogPath),
745
- };
746
- return expandTemplate(template, values);
747
- }
748
- // review plan は成果物を再評価しない。grade の評価結果(サイドカー)の位置と完了条件を示し、
749
- // 評価結果を事実として受け取ってタスクの完了可否を判断させる(bps-task-completion)。
750
- function buildReviewPlanMarkdown(template, task, deliverable, criteria, vpMap, projectId, catalogPath, projectContext, resultRef, stem, reviewGradeOutcome) {
751
- const cpm = task.cpm;
752
- const onCriticalPath = cpm !== undefined && cpm.slack === 0;
753
- const targets = targetDocIds(projectId, deliverable, task.approach, task.local_id);
754
- const meta = {
755
- id: execDocId(projectId, "xrp", stem),
756
- type: "exec-plan",
757
- rulebook: "none",
758
- task_id: task.id,
759
- ...(task.name ? { name: task.name } : {}),
760
- mode: "review",
761
- status: "ready",
762
- project_id: projectId,
763
- ...(task.owner ? { owner: task.owner } : {}),
764
- ...(onCriticalPath ? { on_critical_path: true } : {}),
765
- ...(task.approach ? { approach: task.approach } : {}),
766
- ...(targets.length > 0 ? { targets } : {}),
767
- };
768
- const refs = resolveKataRefs(deliverable?.deliverable.rulebook, deliverable?.deliverable.kind);
769
- const applicableCriteria = applicableReviewCriteria(criteria, vpMap, deliverable?.deliverable.rulebook);
770
- const gradeSubjectPath = gradeFindingTargetPath(task.approach, deliverable, refs);
771
- const values = {
772
- _FRONTMATTER_: frontmatter(meta),
773
- _TASK_ID_: task.id,
774
- _PHASE_DESCRIPTION_: phaseDescriptionText(task),
775
- _DELIVERABLE_NAME_: deliverableName(deliverable),
776
- _DELIVERABLE_DEPENDS_ON_: deliverableDependsOn(deliverable, projectId, catalogPath),
777
- _PROJECT_CONTEXT_: projectContextSection(projectContext, deliverable, task.approach, projectId),
778
- _DELIVERABLE_OVERVIEW_: deliverableOverview(deliverable),
779
- _IMPLEMENTATION_EVIDENCE_: implementationEvidence(deliverable),
780
- _DELIVERABLE_PATH_: deliverablePath(deliverable),
781
- _RESULT_REF_: resultRef,
782
- _RULEBOOK_REF_: refs.rulebook,
783
- _RULEBOOK_INCLUDES_: rulebookIncludesText(deliverable?.deliverable.rulebook, deliverable?.deliverable.kind),
784
- _RECIPE_REF_: refs.recipe,
785
- _SAMPLE_REF_: refs.sample,
786
- _TEMPLATE_REF_: refs.template,
787
- _GRADE_SUBJECT_PATH_: gradeSubjectPath,
788
- _GRADE_TARGET_: gradeTargetKind(task.approach),
789
- _GRADE_RESULT_PATH_: gradeResultRef(projectId, gradeSubjectPath),
790
- _GRADE_SUMMARY_: reviewGradeSummaryText(projectId, gradeSubjectPath, reviewGradeOutcome),
791
- _DONE_CRITERIA_ROWS_: reviewDoneCriteriaRows(applicableCriteria),
792
- };
793
- return expandTemplate(template, values);
794
- }
795
- async function writeTaskPlan(ctx, task, override) {
796
- const mode = task.mode ?? "edit";
797
- const localId = task.local_id;
798
- const targetLocalIds = [...new Set(task.target_local_ids ?? [])];
799
- const crossDeliverables = new Map();
800
- for (const targetLocalId of targetLocalIds) {
801
- const info = ctx.catalogPath ? findDeliverableInfo(ctx.catalogPath, targetLocalId) : null;
802
- if (info)
803
- crossDeliverables.set(targetLocalId, info);
804
- }
805
- const deliverable = override?.deliverable !== undefined
806
- ? override.deliverable
807
- : localId && ctx.catalogPath
808
- ? findDeliverableInfo(ctx.catalogPath, localId)
809
- : null;
810
- // The stem links a plan to its result (both share `<stem>-{plan,result}.md` and the doc id).
811
- // Defaults to the task id (fixed-name worktree/claim flow); in-place callers pass a unique stem.
812
- const stem = override?.stem ?? task.id;
813
- const resultRef = `${repoRelativePath(ctx.executionPath)}/exec/results/${stem}-result.md`;
814
- const outPath = override?.outPath ?? join(ctx.plansDir, `${stem}-plan.md`);
815
- const criteria = deliverable?.deliverable.done_criteria ?? [];
816
- if ((task.execution ?? "agent") === "human") {
817
- throw new Error(`Task ${task.id} has execution: human; claim it to create and use its result instead of a plan.`);
818
- }
819
- const planTask = { ...task, mode };
820
- if (task.approach === "retrofit" && implementationEvidence(deliverable) === MISSING) {
821
- throw new Error(`Task ${task.id} uses approach: retrofit but the target deliverable has no evidence_refs.`);
822
- }
823
- const template = loadPlanTemplate(mode, task.approach, ctx.templateCache);
824
- const body = mode === "review"
825
- ? buildReviewPlanMarkdown(template, planTask, deliverable, criteria, ctx.vpMap, ctx.projectId, ctx.catalogPath, ctx.projectContext, resultRef, stem, ctx.reviewGradeOutcome)
826
- : buildEditPlanMarkdown(template, planTask, deliverable, ctx.roleMap, ctx.vpMap, ctx.projectId, ctx.catalogPath, ctx.projectContext, resultRef, stem, crossDeliverables);
827
- const schemaRef = resolveDeliverableSchemaRef(deliverable?.resolvedPath);
828
- const content = injectCommonConventions(body, schemaRef, ctx.templateCache, mode);
829
- writeFileSync(outPath, content, "utf8");
830
- await formatMarkdownFile(outPath);
831
- return outPath;
832
- }
833
- // Generate the plan for a single agent task without touching other plan files,
834
- // the index, or task state. Human tasks are result-only and are rejected here.
835
- export async function generateSinglePlan(opts) {
836
- if ((opts.task.execution ?? "agent") === "human") {
837
- throw new Error(`Task ${opts.task.id} has execution: human; claim it to create and use its result instead of a plan.`);
838
- }
839
- const ctx = newPlanGenContext(opts);
840
- if (opts.reviewGradeOutcome)
841
- ctx.reviewGradeOutcome = opts.reviewGradeOutcome;
842
- const override = opts.outPath || opts.stem
843
- ? {
844
- ...(opts.outPath ? { outPath: opts.outPath } : {}),
845
- ...(opts.stem ? { stem: opts.stem } : {}),
846
- }
847
- : undefined;
848
- return await writeTaskPlan(ctx, { ...opts.task, mode: opts.task.mode ?? "edit" }, override);
849
- }
850
- // Generate a plan directly from a catalog deliverable, independent of the
851
- // schedule. The slug (`<domain>-<local_id>`) names the plan unless `outPath`
852
- // overrides it. CPM is absent for ad-hoc targets; owner is absent unless the
853
- // caller resolves it (e.g. from sch-strategy owner_rules via a track).
854
- export async function generateDeliverablePlan(opts) {
855
- const ctx = newPlanGenContext(opts);
856
- const task = {
857
- id: opts.target.slug,
858
- local_id: opts.target.localId,
859
- name: opts.target.info.deliverable.name,
860
- mode: opts.mode ?? "edit",
861
- ...(opts.approach ? { approach: opts.approach } : {}),
862
- ...(opts.owner ? { owner: opts.owner } : {}),
863
- schedule_file: "",
864
- fifo_rank: 0,
865
- critical_first_rank: 0,
866
- };
867
- return await writeTaskPlan(ctx, task, {
868
- deliverable: opts.target.info,
869
- ...(opts.outPath ? { outPath: opts.outPath } : {}),
870
- ...(opts.stem ? { stem: opts.stem } : {}),
871
- });
872
- }
873
- function newPlanGenContext(opts) {
874
- const plansDir = join(opts.executionPath, "exec", "plans");
875
- mkdirSync(plansDir, { recursive: true });
876
- return {
877
- plansDir,
878
- executionPath: opts.executionPath,
879
- projectId: opts.projectId,
880
- catalogPath: opts.catalogPath,
881
- vpMap: opts.viewpointsPath
882
- ? loadViewpoints(opts.viewpointsPath)
883
- : new Map(),
884
- roleMap: loadRoles(opts.rolesPath),
885
- projectContext: [
886
- ...(opts.projectContext ??
887
- (opts.projectId ? DEFAULT_PROJECT_CONTEXT : [])),
888
- ],
889
- templateCache: new Map(),
890
- };
891
- }
892
- // Move a completed plan to exec/plans/done/ with a unique UTC + random suffix
893
- // (same convention as event filenames), or delete it. The plan is regenerable
894
- // from the catalog, so deletion is safe; the result remains as the record.
895
- export function archivePlan(opts) {
896
- const plansDir = join(opts.executionPath, "exec", "plans");
897
- const from = join(plansDir, `${opts.slug}-plan.md`);
898
- if (!existsSync(from))
899
- throw new Error(`plan not found: ${from}`);
900
- if (opts.delete) {
901
- rmSync(from, { force: true });
902
- return { from, deleted: true };
903
- }
904
- const doneDir = join(plansDir, "done");
905
- mkdirSync(doneDir, { recursive: true });
906
- const stamp = tsForFilenameUtc(nowUtcIsoSeconds());
907
- const to = join(doneDir, `${opts.slug}-${stamp}-${randomHex(2)}-plan.md`);
908
- renameSync(from, to);
909
- return { from, to, deleted: false };
910
- }
911
- export function planPathForTask(executionPath, taskId) {
912
- return join(executionPath, "exec", "plans", `${taskId}-plan.md`);
913
- }
914
- export function loadPlan(executionPath, taskId) {
915
- const planPath = planPathForTask(executionPath, taskId);
916
- if (existsSync(planPath))
917
- return readFileSync(planPath, "utf8");
918
- return null;
919
- }
920
- const PLAN_APPROACHES = [
921
- "fully-guided",
922
- "recipe-guided",
923
- "freeform",
924
- "bootstrap",
925
- "retrofit",
926
- "cross-deliverable-dedup",
927
- "rulebook-maintenance",
928
- "recipe-maintenance",
929
- "sample-maintenance",
930
- "template-maintenance",
931
- "finalize",
932
- "bootstrap-finalize",
933
- ];
934
- // Parse an exec-plan file's frontmatter to recover the task identity. Returns
935
- // null when the frontmatter is missing or has no usable task_id, in which case
936
- // the caller treats the plan as an ad-hoc plan with no managed identity.
937
- export function parsePlanTaskIdentity(planContent) {
938
- // exec-plan frontmatter は `specdojo:` 名前空間配下にある。
939
- const parsed = readSpecdojoNamespace(planContent);
940
- const taskId = typeof parsed.task_id === "string" ? parsed.task_id.trim() : "";
941
- if (!taskId)
942
- return null;
943
- const mode = parsed.mode === "review" ? "review" : "edit";
944
- const projectId = typeof parsed.project_id === "string" ? parsed.project_id.trim() : "";
945
- const approach = typeof parsed.approach === "string" &&
946
- PLAN_APPROACHES.includes(parsed.approach)
947
- ? parsed.approach
948
- : undefined;
949
- const targets = Array.isArray(parsed.targets)
950
- ? parsed.targets.filter((entry) => typeof entry === "string")
951
- : [];
952
- // 未知の値は採用せず undefined(= schedule)として扱う。
953
- const origin = parsed.origin === "register" || parsed.origin === "schedule"
954
- ? parsed.origin
955
- : undefined;
956
- return {
957
- taskId,
958
- mode,
959
- projectId,
960
- approach,
961
- ...(origin ? { origin } : {}),
962
- ...(targets.length > 0 ? { targets } : {}),
963
- };
964
- }
965
- export function registerGradeFindingsText(projectId, ticketPath) {
966
- if (!existsSync(ticketPath))
967
- return "- なし";
968
- const content = readFileSync(ticketPath, "utf8");
969
- const metadata = readSpecdojoNamespace(content);
970
- const targets = Array.isArray(metadata.targets)
971
- ? metadata.targets
972
- .filter((target) => typeof target === "string")
973
- .map((target) => target.trim())
974
- .filter((target) => target.length > 0)
975
- : [];
976
- if (targets.length === 0)
977
- return "- なし";
978
- const docIndexPath = join(specdojoRootDir(), ".specdojo", "doc-index.json");
979
- const MAX_DOCS = 10;
980
- const MAX_FINDINGS = 20;
981
- const lines = [];
982
- let docCount = 0;
983
- for (const id of targets) {
984
- if (docCount >= MAX_DOCS) {
985
- lines.push(`- その他 ${targets.length - MAX_DOCS} 件の文書は省略されました`);
986
- break;
987
- }
988
- const targetPath = lookupDocIndex(id, docIndexPath);
989
- if (!targetPath)
990
- continue;
991
- const result = readGradeResultForDocument({ documentPath: targetPath, project: projectId });
992
- if (!result || result.findings.length === 0) {
993
- lines.push(`- [[${id}]]: finding なし`);
994
- docCount++;
995
- continue;
996
- }
997
- const sidecarPath = gradeResultPathForDocument({
998
- documentPath: targetPath,
999
- project: projectId,
1000
- });
1001
- // Use posix separators
1002
- const sidecarRel = relative(specdojoRootDir(), sidecarPath).replace(/\\/g, "/");
1003
- lines.push(`- [[${id}]] (サイドカー: \`${sidecarRel}\`):`);
1004
- let findingCount = 0;
1005
- for (const finding of result.findings) {
1006
- if (findingCount >= MAX_FINDINGS) {
1007
- lines.push(` - 他 ${result.findings.length - MAX_FINDINGS} 件の finding があります。詳細はサイドカーを参照してください。`);
1008
- break;
1009
- }
1010
- lines.push(` - [${finding.severity}/${finding.rule}; line=${finding.line}; anchor=${JSON.stringify(finding.anchor)}]: ${gradeFindingDisplayMessage(finding)}`);
1011
- findingCount++;
1012
- }
1013
- docCount++;
1014
- }
1015
- if (lines.length === 0)
1016
- return "- なし";
1017
- return lines.join("\n");
1018
- }