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,252 @@
1
+ import { spawn } from "node:child_process";
2
+ import { existsSync, readFileSync } from "node:fs";
3
+ import { join } from "node:path";
4
+ import { gitEnvironment } from "./git-environment.js";
5
+ import { gradeContentHash, gradeFindingDisplayMessage, gradeResultPathForDocument, parseGradeResult, } from "./grade-result.js";
6
+ export const REVIEW_GRADE_SCRIPT = join("tools", "grade", "run-per-document.sh");
7
+ function errorMessage(error) {
8
+ return error instanceof Error ? error.message : String(error);
9
+ }
10
+ /**
11
+ * Classify a stored grade against the current content of its subject. Only content_hash decides
12
+ * freshness here; comparison-source changes are left to `grade list --dependency-changed`.
13
+ */
14
+ export function classifyReviewGrade(opts) {
15
+ const { content, sidecarPath, sidecarContent } = opts;
16
+ if (sidecarContent === undefined)
17
+ return { state: "missing", sidecarPath };
18
+ let result;
19
+ try {
20
+ result = parseGradeResult(sidecarContent, sidecarPath);
21
+ }
22
+ catch (error) {
23
+ return { state: "unreadable", sidecarPath, reason: errorMessage(error) };
24
+ }
25
+ return result.content_hash === gradeContentHash(content)
26
+ ? { state: "fresh", sidecarPath, result }
27
+ : { state: "stale", sidecarPath, result };
28
+ }
29
+ /** Read the subject and its sidecar from disk and classify the stored grade. */
30
+ export function reviewGradeFreshness(opts) {
31
+ const { subjectPath, projectId, rootDir } = opts;
32
+ if (!subjectPath)
33
+ return { state: "unresolved", reason: "評価対象のパスを解決できない" };
34
+ const absolute = join(rootDir, subjectPath);
35
+ if (!existsSync(absolute)) {
36
+ return { state: "unresolved", reason: `評価対象が存在しない: ${subjectPath}` };
37
+ }
38
+ let sidecarPath;
39
+ let content;
40
+ try {
41
+ content = readFileSync(absolute, "utf8");
42
+ sidecarPath = gradeResultPathForDocument({
43
+ documentPath: subjectPath,
44
+ project: projectId,
45
+ rootDir,
46
+ });
47
+ }
48
+ catch (error) {
49
+ return { state: "unresolved", reason: errorMessage(error) };
50
+ }
51
+ let sidecarContent;
52
+ try {
53
+ sidecarContent = existsSync(sidecarPath) ? readFileSync(sidecarPath, "utf8") : undefined;
54
+ }
55
+ catch (error) {
56
+ return { state: "unreadable", sidecarPath, reason: errorMessage(error) };
57
+ }
58
+ return classifyReviewGrade({ content, sidecarPath, sidecarContent });
59
+ }
60
+ /**
61
+ * Decide whether the runner grades the subject before the review plan is written. A fresh grade is
62
+ * reused; an unresolved subject or a repository without the grade pipeline cannot be graded.
63
+ */
64
+ export function decideReviewGradeAction(opts) {
65
+ const { freshness, scriptAvailable, dryRun } = opts;
66
+ if (freshness.state === "fresh")
67
+ return { run: false, outcome: { action: "skipped" } };
68
+ if (freshness.state === "unresolved") {
69
+ return { run: false, outcome: { action: "not-run", detail: freshness.reason } };
70
+ }
71
+ if (dryRun)
72
+ return { run: false, outcome: { action: "not-run", detail: "dry-run のため実行しない" } };
73
+ if (!scriptAvailable) {
74
+ return {
75
+ run: false,
76
+ outcome: {
77
+ action: "not-run",
78
+ detail: `grade の実行スクリプトがリポジトリにない: ${REVIEW_GRADE_SCRIPT.split("\\").join("/")}`,
79
+ },
80
+ };
81
+ }
82
+ return { run: true };
83
+ }
84
+ export function reviewGradeRunId(taskId, now) {
85
+ const safeTaskId = taskId.replace(/[^A-Za-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "task";
86
+ const stamp = now
87
+ .toISOString()
88
+ .replace(/[-:]/g, "")
89
+ .replace(/\.\d+Z$/, "Z");
90
+ return `review-${safeTaskId}-${stamp}`;
91
+ }
92
+ export function reviewGradeArgs(opts) {
93
+ const args = [
94
+ REVIEW_GRADE_SCRIPT.split("\\").join("/"),
95
+ "--run-id",
96
+ opts.runId,
97
+ "--project",
98
+ opts.projectId,
99
+ "--target",
100
+ opts.target,
101
+ ];
102
+ // kata の対象範囲は --kind で決まる。評価対象の種類を問わず受け付けるよう all を渡す。
103
+ if (opts.target === "kata")
104
+ args.push("--kind", "all");
105
+ args.push("--path", opts.subjectPath);
106
+ return args;
107
+ }
108
+ const defaultInvoke = (command, args, cwd) => new Promise((resolvePromise) => {
109
+ const child = spawn(command, [...args], {
110
+ cwd,
111
+ env: gitEnvironment(),
112
+ stdio: ["ignore", "inherit", "pipe"],
113
+ });
114
+ let stderr = "";
115
+ child.stderr?.on("data", (chunk) => {
116
+ const text = chunk.toString("utf8");
117
+ stderr += text;
118
+ process.stderr.write(text);
119
+ });
120
+ child.on("error", (error) => resolvePromise({ exitCode: 1, stderr: errorMessage(error) }));
121
+ child.on("close", (code) => resolvePromise({ exitCode: code ?? 1, stderr }));
122
+ });
123
+ function lastLine(text) {
124
+ const lines = text
125
+ .split(/\r?\n/)
126
+ .map((line) => line.trim())
127
+ .filter(Boolean);
128
+ return lines.at(-1) ?? "";
129
+ }
130
+ /**
131
+ * Runner-side grade before a review plan is generated. The executor never grades (PJR-2ZVS 3.6).
132
+ * Failures are reported in the outcome instead of thrown so the review can still record
133
+ * grade-stale / grade-unavailable as its verdict.
134
+ */
135
+ export async function ensureReviewGrade(opts) {
136
+ const freshness = reviewGradeFreshness({
137
+ subjectPath: opts.subjectPath,
138
+ projectId: opts.projectId,
139
+ rootDir: opts.repoRoot,
140
+ });
141
+ const decision = decideReviewGradeAction({
142
+ freshness,
143
+ scriptAvailable: existsSync(join(opts.repoRoot, REVIEW_GRADE_SCRIPT)),
144
+ dryRun: opts.dryRun,
145
+ });
146
+ if (!decision.run)
147
+ return decision.outcome;
148
+ const runId = reviewGradeRunId(opts.taskId, opts.now ?? new Date());
149
+ const args = reviewGradeArgs({
150
+ runId,
151
+ projectId: opts.projectId,
152
+ target: opts.target,
153
+ subjectPath: opts.subjectPath,
154
+ });
155
+ const invoke = opts.invoke ?? defaultInvoke;
156
+ try {
157
+ const { exitCode, stderr } = await invoke("bash", args, opts.repoRoot);
158
+ if (exitCode === 0)
159
+ return { action: "executed", runId };
160
+ const reason = lastLine(stderr);
161
+ return {
162
+ action: "failed",
163
+ runId,
164
+ detail: `exit ${exitCode}${reason ? `: ${reason}` : ""}`,
165
+ };
166
+ }
167
+ catch (error) {
168
+ return { action: "failed", runId, detail: errorMessage(error) };
169
+ }
170
+ }
171
+ function outcomeLine(outcome) {
172
+ if (!outcome)
173
+ return undefined;
174
+ switch (outcome.action) {
175
+ case "skipped":
176
+ return "- runner の grade 実行: 省略した(評価対象の `content_hash` が評価結果と一致したため、既存の評価結果を使う)";
177
+ case "executed":
178
+ return `- runner の grade 実行: 実行した(run id: \`${outcome.runId}\`)`;
179
+ case "failed":
180
+ return `- runner の grade 実行: 失敗した(run id: \`${outcome.runId}\`; ${outcome.detail})`;
181
+ case "not-run":
182
+ return `- runner の grade 実行: 実行していない(${outcome.detail})`;
183
+ }
184
+ }
185
+ function freshnessLine(freshness) {
186
+ switch (freshness.state) {
187
+ case "fresh":
188
+ return "- 鮮度: 最新(評価対象の `content_hash` が評価結果の `content_hash` と一致する)";
189
+ case "stale":
190
+ return "- 鮮度: 最新でない(評価対象の `content_hash` が評価結果の `content_hash` と一致しない)。以下は変更前の内容に対する評価結果であり、現在の内容の評価ではない";
191
+ case "missing":
192
+ return "- 鮮度: 評価結果がない(評価結果サイドカーが存在しない)";
193
+ case "unresolved":
194
+ return `- 鮮度: 確認できない(${freshness.reason})`;
195
+ case "unreadable":
196
+ return `- 鮮度: 確認できない(評価結果サイドカーを読み取れない: ${freshness.reason})`;
197
+ }
198
+ }
199
+ function inlineText(value) {
200
+ return value.replace(/\s+/g, " ").trim();
201
+ }
202
+ function gradeResultLines(result) {
203
+ const counts = result.finding_counts;
204
+ const lines = [
205
+ `- \`verdict\`: \`${result.verdict}\``,
206
+ `- \`score\`: ${result.score}`,
207
+ `- \`graded_at\`: ${result.graded_at}(\`graded_by\`: ${result.graded_by})`,
208
+ `- finding 件数: blocker ${counts.blocker ?? 0} / major ${counts.major ?? 0} / minor ${counts.minor ?? 0} / note ${counts.note ?? 0}`,
209
+ "",
210
+ "grade が判定した観点(全観点):",
211
+ "",
212
+ ];
213
+ const viewpoints = Object.entries(result.viewpoints).sort(([a], [b]) => a.localeCompare(b));
214
+ if (viewpoints.length === 0) {
215
+ lines.push("- なし");
216
+ }
217
+ else {
218
+ lines.push("| 観点 | level | score |", "| --- | --- | --- |");
219
+ for (const [id, value] of viewpoints) {
220
+ lines.push(`| \`${id}\` | ${value.level} | ${value.score} |`);
221
+ }
222
+ }
223
+ lines.push("", "finding:", "");
224
+ if (result.findings.length === 0) {
225
+ lines.push("- なし");
226
+ }
227
+ else {
228
+ for (const finding of result.findings) {
229
+ lines.push(`- \`${finding.id}\` [${finding.severity}/\`${finding.rule}\`; line=${finding.line}]: ${inlineText(gradeFindingDisplayMessage(finding))}`);
230
+ }
231
+ }
232
+ return lines;
233
+ }
234
+ /**
235
+ * Render the grade result presented in a review plan. The wording states facts that grade has
236
+ * already settled; it does not ask the reviewer to re-evaluate viewpoints or to raise findings
237
+ * again. Every viewpoint in the result is listed regardless of its evaluation class.
238
+ */
239
+ export function renderReviewGradeSummary(freshness, outcome) {
240
+ const lines = [
241
+ "runner が review の前に確認した評価結果を次に示す。これは grade が確定済みの事実であり、review で観点を評価し直したり、同じ finding を改めて指摘したりしない。",
242
+ "",
243
+ ];
244
+ const runLine = outcomeLine(outcome);
245
+ if (runLine)
246
+ lines.push(runLine);
247
+ lines.push(freshnessLine(freshness));
248
+ if (freshness.state === "fresh" || freshness.state === "stale") {
249
+ lines.push(...gradeResultLines(freshness.result));
250
+ }
251
+ return lines.join("\n");
252
+ }
@@ -1,7 +1,51 @@
1
1
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
2
- import yaml from "js-yaml";
2
+ import { dump, load } from "./yaml.js";
3
3
  import { resolveSpecdojoPath } from "./template-resolution.js";
4
+ import { GRADE_LEVEL_REVIEW_VERDICTS, REVIEW_VERDICTS, describeInvalidReviewVerdict, } from "./review-types.js";
4
5
  export const COMMON_VIEWPOINTS_ID = "specdojo:pm-review-viewpoints";
6
+ function nestedRecord(value) {
7
+ return isRecord(value) ? value : undefined;
8
+ }
9
+ /**
10
+ * Resolve the rulebook ID that represents a document kind. Rulebooks identify themselves,
11
+ * recipes/samples/deliverables refer to their rulebook directly, and templates carry the
12
+ * generated document's rulebook in frontmatter_template.
13
+ */
14
+ export function documentKind(metadata) {
15
+ const direct = metadata["rulebook"];
16
+ if (typeof direct === "string" &&
17
+ !["none", "undecided", "not-needed"].includes(direct) &&
18
+ direct.trim()) {
19
+ return direct;
20
+ }
21
+ const id = metadata["id"];
22
+ if (metadata["type"] === "rulebook" && typeof id === "string" && id.trim())
23
+ return id;
24
+ const frontmatterTemplate = nestedRecord(metadata["frontmatter_template"]);
25
+ const generatedMetadata = nestedRecord(frontmatterTemplate?.["specdojo"]);
26
+ const generatedRulebook = generatedMetadata?.["rulebook"];
27
+ if (typeof generatedRulebook === "string" &&
28
+ !["none", "undecided", "not-needed"].includes(generatedRulebook) &&
29
+ generatedRulebook.trim()) {
30
+ return generatedRulebook;
31
+ }
32
+ return undefined;
33
+ }
34
+ /**
35
+ * Apply a viewpoint's document-kind declaration. Omitted declarations and unclassified
36
+ * documents remain applicable for backward compatibility unless explicitly excluded.
37
+ */
38
+ export function viewpointAppliesToDocument(viewpoint, metadata) {
39
+ const declaration = viewpoint.document_kinds;
40
+ if (!declaration)
41
+ return true;
42
+ const kind = documentKind(metadata);
43
+ if (!kind)
44
+ return declaration.unclassified !== "exclude";
45
+ if (declaration.exclude?.includes(kind))
46
+ return false;
47
+ return declaration.include === undefined || declaration.include.includes(kind);
48
+ }
5
49
  const COLLECTIONS = [
6
50
  ["categories", "id"],
7
51
  ["coverage_types", "id"],
@@ -14,7 +58,7 @@ function isRecord(value) {
14
58
  return typeof value === "object" && value !== null && !Array.isArray(value);
15
59
  }
16
60
  function loadYamlMapping(path) {
17
- const loaded = yaml.load(readFileSync(path, "utf8"));
61
+ const loaded = load(readFileSync(path, "utf8"));
18
62
  if (!isRecord(loaded))
19
63
  throw new Error(`Review viewpoints file is not a YAML mapping: ${path}`);
20
64
  return loaded;
@@ -83,6 +127,65 @@ function mergeCollection(opts) {
83
127
  .filter((itemKey) => !disabledSet.has(itemKey))
84
128
  .map((itemKey) => values.get(itemKey));
85
129
  }
130
+ const VIEWPOINT_EVALUATIONS = [
131
+ "deterministic",
132
+ "referential",
133
+ "discretionary",
134
+ ];
135
+ // Values removed when evaluation was redefined by where the judging criterion lives (PJR-WPWB).
136
+ // Old values are rejected with guidance instead of being ignored.
137
+ const LEGACY_VIEWPOINT_EVALUATIONS = {
138
+ agent: "referential or discretionary",
139
+ human: "referential or discretionary",
140
+ };
141
+ function validateViewpointFields(doc, path) {
142
+ for (const viewpoint of recordArray(doc, "viewpoints", path)) {
143
+ const id = String(viewpoint["id"] ?? "(unknown)");
144
+ // continuous was removed when every viewpoint became a grade target (PJR-K351).
145
+ // Reject it instead of ignoring it so that an overlay cannot silently expect a narrower scope.
146
+ if (Object.hasOwn(viewpoint, "continuous")) {
147
+ throw new Error(`Viewpoint '${id}' uses removed field 'continuous'; every viewpoint is graded, ` +
148
+ `so delete it and narrow scope with grade_targets or document_kinds: ${path}`);
149
+ }
150
+ const value = viewpoint["evaluation"];
151
+ if (value === undefined)
152
+ continue;
153
+ if (typeof value === "string" && value in LEGACY_VIEWPOINT_EVALUATIONS) {
154
+ throw new Error(`Viewpoint '${id}' uses removed evaluation '${value}'; use ${LEGACY_VIEWPOINT_EVALUATIONS[value]} ` +
155
+ `(allowed: ${VIEWPOINT_EVALUATIONS.join(", ")}): ${path}`);
156
+ }
157
+ if (!VIEWPOINT_EVALUATIONS.includes(value)) {
158
+ throw new Error(`Viewpoint '${id}' has unknown evaluation '${String(value)}'; allowed: ${VIEWPOINT_EVALUATIONS.join(", ")}: ${path}`);
159
+ }
160
+ }
161
+ }
162
+ // verdict_definitions は review の verdict と同じ語彙に限る(PJR-XTAN)。grade_rubric の review_verdict は
163
+ // grade の level を review の入力にする写像であり、level から決まる 3 値だけを許す。
164
+ function validateVerdictVocabulary(doc, path) {
165
+ for (const definition of recordArray(doc, "verdict_definitions", path)) {
166
+ const value = definition["id"];
167
+ if (!REVIEW_VERDICTS.includes(value)) {
168
+ throw new Error(`verdict_definitions has ${describeInvalidReviewVerdict(value)}: ${path}`);
169
+ }
170
+ }
171
+ const rubric = doc["grade_rubric"];
172
+ if (rubric === undefined)
173
+ return;
174
+ if (!isRecord(rubric))
175
+ throw new Error(`Review viewpoints 'grade_rubric' must be a mapping: ${path}`);
176
+ const levels = rubric["levels"];
177
+ if (!Array.isArray(levels))
178
+ return;
179
+ for (const level of levels) {
180
+ if (!isRecord(level))
181
+ continue;
182
+ const value = level["review_verdict"];
183
+ if (!GRADE_LEVEL_REVIEW_VERDICTS.includes(value)) {
184
+ throw new Error(`grade_rubric level ${String(level["level"])} review_verdict has ` +
185
+ `${describeInvalidReviewVerdict(value, GRADE_LEVEL_REVIEW_VERDICTS)}: ${path}`);
186
+ }
187
+ }
188
+ }
86
189
  function validateResolvedInheritance(doc, projectPath) {
87
190
  const categories = new Set(recordArray(doc, "categories", projectPath).map((item) => String(item.id)));
88
191
  const coverageTypes = new Set(recordArray(doc, "coverage_types", projectPath).map((item) => String(item.id)));
@@ -142,8 +245,11 @@ export function commonViewpointsPath() {
142
245
  */
143
246
  export function resolveViewpointsDoc(projectPath, commonPath = commonViewpointsPath()) {
144
247
  const project = loadYamlMapping(projectPath);
145
- if (project["extends"] === undefined)
248
+ if (project["extends"] === undefined) {
249
+ validateViewpointFields(project, projectPath);
250
+ validateVerdictVocabulary(project, projectPath);
146
251
  return project;
252
+ }
147
253
  if (project["extends"] !== COMMON_VIEWPOINTS_ID) {
148
254
  throw new Error(`Unsupported review viewpoints inheritance '${String(project["extends"])}'; expected '${COMMON_VIEWPOINTS_ID}': ${projectPath}`);
149
255
  }
@@ -164,6 +270,10 @@ export function resolveViewpointsDoc(projectPath, commonPath = commonViewpointsP
164
270
  }
165
271
  delete resolved["extends"];
166
272
  delete resolved["disabled"];
273
+ validateViewpointFields(common, commonPath);
274
+ validateViewpointFields(project, projectPath);
275
+ validateVerdictVocabulary(common, commonPath);
276
+ validateVerdictVocabulary(project, projectPath);
167
277
  validateResolvedInheritance(resolved, projectPath);
168
278
  return resolved;
169
279
  }
@@ -194,6 +304,6 @@ export function scaffoldViewpoints(opts) {
194
304
  const dir = outputPath.includes("/") ? outputPath.slice(0, outputPath.lastIndexOf("/")) : ".";
195
305
  if (!existsSync(dir))
196
306
  mkdirSync(dir, { recursive: true });
197
- writeFileSync(outputPath, yaml.dump(doc, { lineWidth: 120, noRefs: true }), "utf8");
307
+ writeFileSync(outputPath, dump(doc, { lineWidth: 120, noRefs: true }), "utf8");
198
308
  return { written: true, skipped: false };
199
309
  }
@@ -1 +1,40 @@
1
- export {};
1
+ // review の verdict。タスクの完了可否を表す唯一の語彙であり、bps-task-completion の検証・受入観点
2
+ // 6 区分と一対一に対応する。pm-review-viewpoints.yaml の verdict_definitions と review result の
3
+ // verdict はこの値を共有する(PJR-XTAN)。grade の文書 verdict(pass / needs-work / fail)は成果物の
4
+ // 品質という別の対象を判定するため、この語彙へ統一しない。
5
+ export const REVIEW_VERDICTS = [
6
+ "complete",
7
+ "complete-with-findings",
8
+ "incomplete",
9
+ "grade-stale",
10
+ "grade-unavailable",
11
+ "changed-during-review",
12
+ ];
13
+ // grade の level から写像できる verdict。鮮度や評価不能は grade の level から決まらないため含めない。
14
+ export const GRADE_LEVEL_REVIEW_VERDICTS = [
15
+ "complete",
16
+ "complete-with-findings",
17
+ "incomplete",
18
+ ];
19
+ // タスクの完了可否を表していた旧語彙と、その移行先。旧値は無視せず、移行先を示して拒否する。
20
+ // verdict_definitions の旧値と、xrr-template.md の decision.recommendation の旧値を含む。
21
+ export const LEGACY_REVIEW_VERDICTS = {
22
+ pass: "complete",
23
+ conditional_pass: "complete-with-findings",
24
+ changes_requested: "incomplete",
25
+ blocked: "grade-stale, grade-unavailable, or changed-during-review",
26
+ approve: "complete or complete-with-findings",
27
+ revise: "incomplete",
28
+ reject: "incomplete",
29
+ };
30
+ export function isReviewVerdict(value) {
31
+ return typeof value === "string" && REVIEW_VERDICTS.includes(value);
32
+ }
33
+ /** Explain why a value is not a review verdict, naming the replacement for a legacy value. */
34
+ export function describeInvalidReviewVerdict(value, allowed = REVIEW_VERDICTS) {
35
+ const shown = typeof value === "string" ? `'${value}'` : String(value);
36
+ if (typeof value === "string" && Object.hasOwn(LEGACY_REVIEW_VERDICTS, value)) {
37
+ return `removed verdict ${shown}; use ${LEGACY_REVIEW_VERDICTS[value]} (allowed: ${allowed.join(", ")})`;
38
+ }
39
+ return `unknown verdict ${shown}; allowed: ${allowed.join(", ")}`;
40
+ }