specdojo 0.2.0 → 0.3.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 (170) hide show
  1. package/.github/agents/specdojo-orchestrator.md +165 -0
  2. package/CHANGELOG.md +280 -0
  3. package/README.md +143 -30
  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/dashboard.js +140 -9
  8. package/dist/devcontainer-command.js +43 -0
  9. package/dist/devcontainer-scaffold.js +165 -0
  10. package/dist/exec-agent-config.js +107 -9
  11. package/dist/exec-agent-git-state.js +18 -0
  12. package/dist/exec-agent-protected-config.js +46 -8
  13. package/dist/exec-evidence.js +254 -11
  14. package/dist/exec-format.js +13 -4
  15. package/dist/exec-handoff.js +336 -0
  16. package/dist/exec-parent-validation.js +317 -43
  17. package/dist/exec-pipeline-state.js +74 -9
  18. package/dist/exec-plans.js +115 -113
  19. package/dist/exec-protection-handoff.js +43 -2
  20. package/dist/exec-provider-scaffold.js +247 -15
  21. package/dist/exec-register-resume.js +65 -19
  22. package/dist/exec-register.js +9 -3
  23. package/dist/exec-repo-integration.js +811 -0
  24. package/dist/exec-repo-trace.js +182 -0
  25. package/dist/exec-reporter.js +613 -132
  26. package/dist/exec-results.js +81 -56
  27. package/dist/exec-run-lock.js +110 -107
  28. package/dist/exec-run.js +1585 -356
  29. package/dist/exec-shared.js +7 -0
  30. package/dist/exec-slot-lock.js +242 -0
  31. package/dist/exec-task-repos.js +415 -0
  32. package/dist/exec-trial.js +51 -25
  33. package/dist/exec-worktree-command.js +87 -43
  34. package/dist/exec-worktree-ops.js +502 -57
  35. package/dist/exec-worktree.js +114 -27
  36. package/dist/exec.js +13 -6
  37. package/dist/grade-result.js +128 -0
  38. package/dist/grade.js +809 -72
  39. package/dist/init-command.js +443 -0
  40. package/dist/job.js +160 -10
  41. package/dist/orchestrator.js +213 -0
  42. package/dist/package-paths.js +19 -1
  43. package/dist/register-event-merge.js +169 -0
  44. package/dist/register-item.js +7 -1
  45. package/dist/register.js +294 -86
  46. package/dist/review-grade.js +252 -0
  47. package/dist/review-plan.js +111 -1
  48. package/dist/review-types.js +40 -1
  49. package/dist/routine.js +72 -5
  50. package/dist/schedule-build.js +2 -2
  51. package/dist/schedule.js +17 -4
  52. package/dist/specdojo-config.js +466 -20
  53. package/dist/specdojo-gitignore.js +135 -0
  54. package/dist/specdojo.js +8 -1
  55. package/dist/viewpoint-document-kinds-check.js +128 -0
  56. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +348 -90
  57. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +51 -17
  58. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +7 -5
  59. package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +29 -31
  60. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +34 -55
  61. package/docs/ja/specdojo/exec-templates/xrp-job-template.md +54 -0
  62. package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +28 -37
  63. package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +29 -34
  64. package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +30 -30
  65. package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +29 -34
  66. package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +29 -34
  67. package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +29 -34
  68. package/docs/ja/specdojo/exec-templates/xrp-template.md +29 -28
  69. package/docs/ja/specdojo/exec-templates/xrr-template.md +11 -9
  70. package/docs/ja/specdojo/guides/docs-editing-guide.md +20 -0
  71. package/docs/ja/specdojo/guides/docs-structure-guide.md +103 -70
  72. package/docs/ja/specdojo/guides/exec-config-guide.md +91 -47
  73. package/docs/ja/specdojo/guides/exec-operation-guide.md +124 -27
  74. package/docs/ja/specdojo/guides/exec-worktree-guide.md +40 -11
  75. package/docs/ja/specdojo/guides/kata-guide.md +4 -4
  76. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +25 -4
  77. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +1 -1
  78. package/docs/ja/specdojo/guides/practice-system-composition-guide.md +13 -13
  79. package/docs/ja/specdojo/guides/quick-start-guide.md +261 -32
  80. package/docs/ja/specdojo/guides/register-operation-guide.md +31 -14
  81. package/docs/ja/specdojo/guides/release-v0-3-0-migration-guide.md +264 -0
  82. package/docs/ja/specdojo/guides/remote-host-development-guide.md +184 -0
  83. package/docs/ja/specdojo/guides/review-guide.md +195 -158
  84. package/docs/ja/specdojo/guides/routine-operation-guide.md +74 -9
  85. package/docs/ja/specdojo/guides/ryu-guide.md +32 -30
  86. package/docs/ja/specdojo/guides/schedule-design-guide.md +10 -10
  87. package/docs/ja/specdojo/guides/schedule-operation-guide.md +1 -1
  88. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +58 -33
  89. package/docs/ja/specdojo/guides/use-case-guide.md +3 -3
  90. package/docs/ja/specdojo/guides/waza-guide.md +15 -2
  91. package/docs/ja/specdojo/index.md +2 -2
  92. package/docs/ja/specdojo/philosophy/specdojo-philosophy.md +5 -5
  93. package/docs/ja/specdojo/recipes/bps-recipe.md +213 -0
  94. package/docs/ja/specdojo/recipes/pm-members-recipe.md +52 -117
  95. package/docs/ja/specdojo/references/command-reference.md +336 -93
  96. package/docs/ja/specdojo/references/deliverables-reference.md +1 -1
  97. package/docs/ja/specdojo/references/directory-layout-reference.md +13 -9
  98. package/docs/ja/specdojo/references/specdojo-config-reference.md +107 -24
  99. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +132 -220
  100. package/docs/ja/specdojo/rulebooks/br-rulebook.md +6 -44
  101. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +2 -0
  102. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +0 -87
  103. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +61 -39
  104. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +0 -87
  105. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +1 -33
  106. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +0 -137
  107. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +0 -247
  108. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +0 -83
  109. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +4 -2
  110. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +78 -150
  111. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +5 -4
  112. package/docs/ja/specdojo/rulebooks/sch-rulebook.md +1 -1
  113. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +0 -11
  114. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +0 -61
  115. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +2 -47
  116. package/docs/ja/specdojo/samples/bps-sample.md +74 -21
  117. package/docs/ja/specdojo/samples/gl-sample.yaml +17 -1
  118. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +28 -0
  119. package/docs/ja/specdojo/samples/pm-members-sample.yaml +2 -67
  120. package/docs/ja/specdojo/samples/pm-organization-sample.md +8 -7
  121. package/docs/ja/specdojo/samples/pm-raci-sample.md +1 -1
  122. package/docs/ja/specdojo/samples/tml-sample.yaml +40 -0
  123. package/docs/ja/specdojo/standards/document-metadata-standard.md +21 -16
  124. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +14 -14
  125. package/docs/ja/specdojo/standards/job-definition-standard.md +37 -17
  126. package/docs/ja/specdojo/standards/people-and-organization-definition-standard.md +37 -32
  127. package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +1 -1
  128. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +21 -11
  129. package/docs/ja/specdojo/templates/agent-members-template.yaml +25 -0
  130. package/docs/ja/specdojo/templates/bps-template.md +91 -0
  131. package/docs/ja/specdojo/templates/pm-members-template.yaml +2 -59
  132. package/docs/specdojo/schemas/v1/agent-members.schema.yaml +76 -0
  133. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +4 -2
  134. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +55 -2
  135. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +93 -6
  136. package/docs/specdojo/schemas/v1/exec-reporter-output.schema.yaml +27 -78
  137. package/docs/specdojo/schemas/v1/gl.schema.yaml +87 -0
  138. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +33 -0
  139. package/docs/specdojo/schemas/v1/job-run.schema.yaml +27 -0
  140. package/docs/specdojo/schemas/v1/job.schema.yaml +25 -0
  141. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +49 -1
  142. package/docs/specdojo/schemas/v1/pm-members.schema.yaml +9 -169
  143. package/docs/specdojo/schemas/v1/pm-review-viewpoints.schema.yaml +100 -10
  144. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +13 -0
  145. package/docs/specdojo/schemas/v1/routine-run.schema.yaml +3 -0
  146. package/docs/specdojo/schemas/v1/routine.schema.yaml +7 -0
  147. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +110 -0
  148. package/package.json +16 -9
  149. package/templates/antigravity/README.md +60 -0
  150. package/templates/antigravity/agent-members-snippet.yaml +61 -0
  151. package/templates/antigravity/exec-defaults-snippet.yaml +39 -0
  152. package/templates/antigravity/orchestrator.md +157 -0
  153. package/templates/antigravity/settings.global.json +55 -0
  154. package/templates/claude/agents/claude-executor.md +14 -0
  155. package/templates/claude/agents/claude-reporter.md +16 -0
  156. package/templates/claude/agents/specdojo-orchestrator.md +164 -0
  157. package/templates/claude/settings.edit.json +27 -1
  158. package/templates/codex/README.md +5 -4
  159. package/templates/codex/agents/specdojo-orchestrator.toml +165 -0
  160. package/templates/codex/orchestrator.md +157 -0
  161. package/templates/copilot/README.md +7 -5
  162. package/templates/copilot/{pm-members-snippet.yaml → agent-members-snippet.yaml} +4 -2
  163. package/templates/devcontainer/devcontainer.json +27 -0
  164. package/templates/devcontainer/emacs/init.el +88 -0
  165. package/templates/devcontainer/post-create.sh +62 -0
  166. package/templates/init-agent-members.yaml +200 -0
  167. package/templates/init-exec-defaults.yaml +72 -0
  168. package/templates/opencode/agents/specdojo-orchestrator.md +204 -0
  169. package/docs/ja/specdojo/exec-templates/xrp-viewpoint-detail-template.md +0 -7
  170. package/docs/ja/specdojo/exec-templates/xrr-viewpoint-detail-template.md +0 -7
package/dist/grade.js CHANGED
@@ -4,14 +4,16 @@ import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep }
4
4
  import yaml from "js-yaml";
5
5
  import remarkParse from "remark-parse";
6
6
  import { unified } from "unified";
7
- import { extractJsonText } from "./agent-response.js";
7
+ import { extractJsonArrayText, extractJsonText } from "./agent-response.js";
8
8
  import { collectResolvedDeliverables, loadCatalogDocs } from "./catalog-build.js";
9
9
  import { isTrashedPath, resolveBasePath } from "./catalog-paths.js";
10
- import { resolveViewpointsDoc } from "./review-plan.js";
11
- import { assertValidActor, getProjectCatalogPath, getProjectExecutionPath, getProjectViewpointsPath, loadConfig, loadMemberRoster, specdojoRootDir, } from "./specdojo-config.js";
10
+ import { resolveViewpointsDoc, viewpointAppliesToDocument } from "./review-plan.js";
11
+ import { assertValidActor, getProjectCatalogPath, getProjectExecutionPath, getProjectMembersPath, getProjectRolesPath, getProjectSchedulePath, getProjectViewpointsPath, loadConfig, loadMemberRoster, specdojoRootDir, } from "./specdojo-config.js";
12
12
  import { listFilesRecursive } from "./exec-shared.js";
13
+ import { buildScheduleIndex } from "./exec-schedule-index.js";
13
14
  import { resolveSpecdojoPath } from "./template-resolution.js";
14
- import { gradeContentHash, gradeFindingCount, gradeResultPath, markdownDocumentId, readGradeResult, readGradeResultForDocument, resolveGradeResultsDirectory, validateGradeResult, writeGradeResult, } from "./grade-result.js";
15
+ import { applyGradeFindingTranslations, gradeContentHash, gradeFindingCount, gradeFindingTranslationInput, gradeResultPath, gradeResultPathForDocument, markdownDocumentId, readGradeResult, readGradeResultForDocument, resolveGradeResultsDirectory, validateGradeResult, writeGradeResult, } from "./grade-result.js";
16
+ const GRADE_TARGETS = ["kata", "deliverable"];
15
17
  const FINDING_RE = /^[ \t]*<!--[ \t]*specdojo:finding[ \t]+id=([^ \t]+)[ \t]+severity=(blocker|major|minor|note)[ \t]+rule=([^ \t]+)(?:[ \t]+line=([1-9][0-9]*))?[ \t]+(.*?)[ \t]*-->[ \t]*(?:\r?\n|$)/gm;
16
18
  const KATA_DIRS = ["rulebooks", "recipes", "samples", "templates"];
17
19
  const KATA_REFERENCE_EXTENSIONS = new Set([".md", ".yaml", ".yml", ".json"]);
@@ -22,6 +24,7 @@ const DONE_CRITERIA_SCHEMA = "docs/specdojo/schemas/v1/grade-done-criteria.schem
22
24
  const GRADE_PLACEHOLDER = "__SPECDOJO_GRADE_FLOW_PLACEHOLDER__";
23
25
  const GRADE_FINDINGS_PLACEHOLDER = "__SPECDOJO_GRADE_FINDINGS_FLOW_PLACEHOLDER__";
24
26
  const GRADE_UNSATISFIED_PLACEHOLDER = "__SPECDOJO_GRADE_UNSATISFIED_BLOCK_PLACEHOLDER__";
27
+ export const GRADE_PLAN_EMBEDDED_DOCUMENT_CHARACTER_LIMIT = 100_000;
25
28
  const SEVERITY_LEVEL_CAP = {
26
29
  blocker: 0,
27
30
  major: 2,
@@ -82,6 +85,22 @@ function levelCapForFindings(findings) {
82
85
  const severityCap = findings.reduce((current, finding) => Math.min(current, SEVERITY_LEVEL_CAP[finding.severity]), 4);
83
86
  return majorCount >= 2 ? Math.min(severityCap, 1) : severityCap;
84
87
  }
88
+ function correctViewpointLevels(viewpoints) {
89
+ const corrections = [];
90
+ const corrected = viewpoints.map((viewpoint) => {
91
+ const cap = levelCapForFindings(viewpoint.findings ?? []);
92
+ const correctedLevel = Math.min(viewpoint.level, cap);
93
+ if (correctedLevel !== viewpoint.level) {
94
+ corrections.push({
95
+ viewpoint: viewpoint.id,
96
+ original_level: viewpoint.level,
97
+ corrected_level: correctedLevel,
98
+ });
99
+ }
100
+ return { ...viewpoint, level: correctedLevel };
101
+ });
102
+ return { viewpoints: corrected, corrections };
103
+ }
85
104
  function isRecord(value) {
86
105
  return typeof value === "object" && value !== null && !Array.isArray(value);
87
106
  }
@@ -303,10 +322,17 @@ function loadViewpoints(projectOption) {
303
322
  throw new Error("viewpoints_path is required for grade");
304
323
  return resolveViewpointsDoc(resolve(specdojoRootDir(), path));
305
324
  }
325
+ // 対象探索は観点定義が無いプロジェクトでも動かす。その場合は突き合わせ先を持たない扱いにする。
326
+ function loadViewpointsIfConfigured(projectOption, rootDir) {
327
+ const path = getProjectViewpointsPath(resolveProject(projectOption).project);
328
+ if (!path || !existsSync(resolve(rootDir, path)))
329
+ return undefined;
330
+ return resolveViewpointsDoc(resolve(rootDir, path));
331
+ }
306
332
  export function resolveGradeActor(actor, roster) {
307
333
  const normalized = actor.trim();
308
334
  if (!normalized)
309
- throw new Error("--by must be a non-empty pm-members.yaml nickname");
335
+ throw new Error("--by must be a non-empty agent-members.yaml nickname");
310
336
  if (!roster)
311
337
  throw new Error("members_path is required for grade apply --by");
312
338
  assertValidActor(normalized, roster);
@@ -319,6 +345,15 @@ function assertRubric(doc) {
319
345
  const rubric = doc.grade_rubric;
320
346
  if (!rubric)
321
347
  throw new Error("Resolved viewpoints do not define grade_rubric");
348
+ // すべての観点が grade の対象なので、重みのない category の観点は score へ黙って入らなくなる。
349
+ for (const viewpoint of doc.viewpoints ?? []) {
350
+ for (const target of viewpoint.grade_targets ?? GRADE_TARGETS) {
351
+ const weight = rubric.weights[target]?.[viewpoint.category];
352
+ if (typeof weight !== "number" || weight <= 0) {
353
+ throw new Error(`grade_rubric ${rubric.id} has no ${target} weight for category '${viewpoint.category}' used by ${viewpoint.id}`);
354
+ }
355
+ }
356
+ }
322
357
  return rubric;
323
358
  }
324
359
  function relativePathFromRoot(path, rootDir) {
@@ -527,6 +562,8 @@ function loadDeliverableCatalog(projectOption, root = specdojoRootDir()) {
527
562
  entries.set(path, {
528
563
  path,
529
564
  localId: item.item.local_id,
565
+ dependsOn: item.item.depends_on,
566
+ entryHash: gradeContentHash(stableJson(item.item)),
530
567
  doneCriteria: (item.item.done_criteria ?? []).map((criterion, index) => ({
531
568
  id: criterionId(index),
532
569
  text: criterion.text,
@@ -552,6 +589,143 @@ export function resolveDeliverableDoneCriteria(paths, projectOption) {
552
589
  }
553
590
  return result;
554
591
  }
592
+ // キー順に依存しない直列化。カタログ項目の hash が YAML 上のキー順の入れ替えで変わらないようにする。
593
+ function stableJson(value) {
594
+ if (Array.isArray(value))
595
+ return `[${value.map((item) => stableJson(item)).join(",")}]`;
596
+ if (isRecord(value)) {
597
+ const keys = Object.keys(value)
598
+ .filter((key) => value[key] !== undefined)
599
+ .sort();
600
+ return `{${keys.map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
601
+ }
602
+ return JSON.stringify(value) ?? "null";
603
+ }
604
+ // 突き合わせ先の変更検出(PJR-Z47X)。観点が comparison_sources で宣言した突き合わせ先と、
605
+ // 成果物の depends_on 先の hash を grade result の source_hashes へ記録し、
606
+ // --changed-only と --dependency-changed が現在の hash と比較する。
607
+ const COMPARISON_SOURCE_RE = /^(catalog-entry|dependencies|schedule|members|roles|deliverable:[a-z0-9][a-z0-9-]*)$/;
608
+ // 突き合わせ先が存在しないことも状態として記録し、後から作られた場合に変更として検出する。
609
+ const ABSENT_SOURCE_HASH = gradeContentHash("specdojo:grade-comparison-source-absent");
610
+ function createGradeSourceContext(projectOption, rootDir) {
611
+ return {
612
+ rootDir,
613
+ project: resolveProject(projectOption).project,
614
+ projectOption,
615
+ hashes: new Map(),
616
+ };
617
+ }
618
+ function sourceCatalog(context) {
619
+ if (!context.catalog || !context.localIdToPath) {
620
+ context.catalog = getProjectCatalogPath(context.project)
621
+ ? loadDeliverableCatalog(context.projectOption, context.rootDir)
622
+ : new Map();
623
+ context.localIdToPath = new Map([...context.catalog.entries()].map(([path, entry]) => [entry.localId, path]));
624
+ }
625
+ return { catalog: context.catalog, localIdToPath: context.localIdToPath };
626
+ }
627
+ function hashSourceFile(path) {
628
+ if (!path || !existsSync(path))
629
+ return ABSENT_SOURCE_HASH;
630
+ return gradeContentHash(readFileSync(path, "utf8"));
631
+ }
632
+ // ディレクトリはファイルの相対パスと内容の組で hash する。生成物は生成元の変更で検出する。
633
+ function hashSourceDirectory(path) {
634
+ const files = listFilesRecursive(path)
635
+ .filter((file) => !relativePathFromRoot(file, path).split("/").includes("generated"))
636
+ .sort();
637
+ if (files.length === 0)
638
+ return ABSENT_SOURCE_HASH;
639
+ const hash = createHash("sha256");
640
+ for (const file of files) {
641
+ hash.update(`${relativePathFromRoot(file, path)}\0${hashSourceFile(file)}\n`);
642
+ }
643
+ return hash.digest("hex");
644
+ }
645
+ function sharedSourceHash(key, context) {
646
+ const cached = context.hashes.get(key);
647
+ if (cached !== undefined)
648
+ return cached;
649
+ let hash;
650
+ if (key === "schedule") {
651
+ hash = hashSourceDirectory(resolve(context.rootDir, getProjectSchedulePath(context.project)));
652
+ }
653
+ else if (key === "members" || key === "roles") {
654
+ const path = key === "members"
655
+ ? getProjectMembersPath(context.project)
656
+ : getProjectRolesPath(context.project);
657
+ hash = hashSourceFile(path ? resolve(context.rootDir, path) : undefined);
658
+ }
659
+ else {
660
+ const localId = key.slice(key.indexOf(":") + 1);
661
+ hash = hashSourceFile(sourceCatalog(context).localIdToPath.get(localId));
662
+ }
663
+ context.hashes.set(key, hash);
664
+ return hash;
665
+ }
666
+ function gradedComparisonSources(viewpoints, target, metadata) {
667
+ if (!viewpoints)
668
+ return [];
669
+ const sources = new Set();
670
+ for (const viewpoint of gradedViewpoints(viewpoints, target, metadata)) {
671
+ for (const source of viewpoint.comparison_sources ?? []) {
672
+ if (!COMPARISON_SOURCE_RE.test(source)) {
673
+ throw new Error(`${viewpoint.id}: unknown comparison source ${source}`);
674
+ }
675
+ sources.add(source);
676
+ }
677
+ }
678
+ return [...sources].sort();
679
+ }
680
+ // depends_on のうちカタログで Markdown 成果物に解決できるものだけを依存先として扱う。
681
+ function dependencySourceKeys(documentPath, context) {
682
+ const { catalog, localIdToPath } = sourceCatalog(context);
683
+ return (catalog.get(documentPath)?.dependsOn ?? [])
684
+ .filter((localId) => localIdToPath.has(localId))
685
+ .map((localId) => `dependency:${localId}`)
686
+ .sort();
687
+ }
688
+ function comparisonSourceKeys(sources, documentPath, context) {
689
+ return sources.flatMap((source) => source === "dependencies" ? dependencySourceKeys(documentPath, context) : [source]);
690
+ }
691
+ function currentSourceHashes(keys, documentPath, context) {
692
+ const hashes = {};
693
+ for (const key of [...new Set(keys)].sort()) {
694
+ if (key === "catalog-entry") {
695
+ hashes[key] =
696
+ sourceCatalog(context).catalog.get(documentPath)?.entryHash ?? ABSENT_SOURCE_HASH;
697
+ }
698
+ else if (key.startsWith("dependency:")) {
699
+ const localId = key.slice("dependency:".length);
700
+ hashes[key] = hashSourceFile(sourceCatalog(context).localIdToPath.get(localId));
701
+ }
702
+ else {
703
+ hashes[key] = sharedSourceHash(key, context);
704
+ }
705
+ }
706
+ return hashes;
707
+ }
708
+ // grade result へ記録する突き合わせ先の hash。宣言された突き合わせ先に加え、成果物では
709
+ // --dependency-changed が使う depends_on 先を、観点の宣言に関係なく記録する。
710
+ function gradeSourceHashes(documentPath, document, viewpoints, target, context) {
711
+ const metadata = isRecord(document.data.specdojo) ? document.data.specdojo : {};
712
+ const keys = [
713
+ ...comparisonSourceKeys(gradedComparisonSources(viewpoints, target, metadata), documentPath, context),
714
+ ...(target === "deliverable" ? dependencySourceKeys(documentPath, context) : []),
715
+ ];
716
+ return currentSourceHashes(keys, documentPath, context);
717
+ }
718
+ /** Current hashes of the comparison sources and dependencies that grade apply records for a document. */
719
+ export function resolveGradeSourceHashes(opts, rootDir = specdojoRootDir()) {
720
+ const absolute = resolveSafeMarkdownPath(opts.path, rootDir);
721
+ const document = parseMarkdown(readFileSync(absolute, "utf8"), relativePathFromRoot(absolute, rootDir));
722
+ const viewpoints = opts.viewpoints ?? loadViewpointsIfConfigured(opts.project, rootDir);
723
+ return gradeSourceHashes(absolute, document, viewpoints, opts.target, createGradeSourceContext(opts.project, rootDir));
724
+ }
725
+ // 記録の無い突き合わせ先(source tracking 導入前の結果を含む)は、鮮度を保証できないため変更として扱う。
726
+ function sourceHashesChanged(stored, current) {
727
+ return Object.entries(current).some(([key, hash]) => stored?.[key] !== hash);
728
+ }
555
729
  function gradePipelineStateDirectory(projectOption, rootDir = specdojoRootDir()) {
556
730
  const { project } = resolveProject(projectOption);
557
731
  return resolve(rootDir, getProjectExecutionPath(project), "grade", "pipeline");
@@ -755,16 +929,64 @@ export function discoverGradeTargets(opts, rootDir = specdojoRootDir()) {
755
929
  .filter((path) => !isTrashedGradeTarget(path, rootDir))
756
930
  .sort();
757
931
  if (!opts.changedOnly &&
932
+ !opts.dependencyChanged &&
933
+ !opts.rulebookChanged &&
934
+ !opts.unreviewed &&
758
935
  opts.verdict === undefined &&
759
936
  opts.minScore === undefined &&
760
937
  opts.maxFindings === undefined &&
761
938
  !opts.ungraded &&
762
- !opts.incomplete) {
939
+ !opts.incomplete &&
940
+ !opts.rubricOutdated) {
763
941
  return unique;
764
942
  }
765
943
  const pipelineStates = opts.incomplete
766
944
  ? loadGradePipelineStates(opts.project, rootDir)
767
945
  : new Map();
946
+ const sourceContext = createGradeSourceContext(opts.project, rootDir);
947
+ const viewpoints = opts.changedOnly || opts.rubricOutdated
948
+ ? loadViewpointsIfConfigured(opts.project, rootDir)
949
+ : undefined;
950
+ const currentRubricId = opts.rubricOutdated ? currentGradeRubricId(viewpoints) : undefined;
951
+ let scheduledDocuments;
952
+ if (opts.unreviewed) {
953
+ const { project } = resolveProject(opts.project);
954
+ const schedulePath = join(rootDir, getProjectExecutionPath(project), "../schedule");
955
+ try {
956
+ const index = buildScheduleIndex(schedulePath);
957
+ scheduledDocuments = new Set();
958
+ for (const node of index.nodes.values()) {
959
+ if (node.local_id)
960
+ scheduledDocuments.add(node.local_id);
961
+ if (node.target_local_ids) {
962
+ for (const tid of node.target_local_ids)
963
+ scheduledDocuments.add(tid);
964
+ }
965
+ }
966
+ }
967
+ catch {
968
+ scheduledDocuments = new Set();
969
+ }
970
+ }
971
+ const gradeDates = new Map();
972
+ function getMemoizedGradeDate(p) {
973
+ if (!gradeDates.has(p)) {
974
+ const res = readGradeResultForDocument({
975
+ documentPath: relativePathFromRoot(p, rootDir),
976
+ project: opts.project,
977
+ rootDir,
978
+ });
979
+ gradeDates.set(p, res ? new Date(res.graded_at).getTime() : 0);
980
+ }
981
+ return gradeDates.get(p);
982
+ }
983
+ function getRulebookPath(rulebookId) {
984
+ if (rulebookId.startsWith("specdojo:")) {
985
+ const id = rulebookId.slice("specdojo:".length);
986
+ return join(rootDir, "docs/ja/specdojo/rulebooks", `${id}.md`);
987
+ }
988
+ return undefined;
989
+ }
768
990
  return unique.filter((path) => {
769
991
  const rel = relativePathFromRoot(path, rootDir);
770
992
  const content = readFileSync(path, "utf8");
@@ -775,12 +997,9 @@ export function discoverGradeTargets(opts, rootDir = specdojoRootDir()) {
775
997
  project: opts.project,
776
998
  rootDir,
777
999
  });
778
- if (opts.incomplete && !isIncompleteGradePipelineState(pipelineState))
779
- return false;
780
- if (opts.ungraded && result !== undefined)
781
- return false;
782
- if (opts.verdict !== undefined && result?.verdict !== opts.verdict)
1000
+ if (opts.verdict !== undefined && (result === undefined || result.verdict !== opts.verdict)) {
783
1001
  return false;
1002
+ }
784
1003
  if (opts.minScore !== undefined && (result === undefined || result.score < opts.minScore)) {
785
1004
  return false;
786
1005
  }
@@ -788,9 +1007,82 @@ export function discoverGradeTargets(opts, rootDir = specdojoRootDir()) {
788
1007
  (result === undefined || gradeFindingCount(result) > opts.maxFindings)) {
789
1008
  return false;
790
1009
  }
791
- return !opts.changedOnly || result?.content_hash !== gradeContentHash(content);
1010
+ if (opts.unreviewed) {
1011
+ if (!scheduledDocuments)
1012
+ return false;
1013
+ const id = document.data.specdojo?.id;
1014
+ if (!id || scheduledDocuments.has(id.split(":").pop()))
1015
+ return false;
1016
+ if (result !== undefined && result.content_hash === gradeContentHash(content))
1017
+ return false;
1018
+ }
1019
+ if (opts.incomplete && pipelineState) {
1020
+ if (!isIncompleteGradePipelineState(pipelineState))
1021
+ return false;
1022
+ }
1023
+ else if (opts.incomplete) {
1024
+ return false;
1025
+ }
1026
+ if (opts.ungraded && result !== undefined)
1027
+ return false;
1028
+ if (currentRubricId !== undefined && !isGradeRubricOutdated(result, currentRubricId)) {
1029
+ return false;
1030
+ }
1031
+ if (result === undefined) {
1032
+ if (opts.dependencyChanged || opts.rulebookChanged)
1033
+ return false;
1034
+ return true;
1035
+ }
1036
+ const docDate = new Date(result.graded_at).getTime();
1037
+ if (opts.rulebookChanged) {
1038
+ const rb = document.data.specdojo?.rulebook;
1039
+ if (!rb)
1040
+ return false;
1041
+ const rbPath = getRulebookPath(rb);
1042
+ if (!rbPath || !existsSync(rbPath))
1043
+ return false;
1044
+ if (getMemoizedGradeDate(rbPath) <= docDate)
1045
+ return false;
1046
+ }
1047
+ // 依存先の評価日時ではなく内容の hash で判定する。再評価しただけの依存先は変更扱いにしない。
1048
+ if (opts.dependencyChanged) {
1049
+ if (opts.target !== "deliverable")
1050
+ return false;
1051
+ const keys = dependencySourceKeys(path, sourceContext);
1052
+ if (keys.length === 0)
1053
+ return false;
1054
+ const current = currentSourceHashes(keys, path, sourceContext);
1055
+ if (!sourceHashesChanged(result.source_hashes, current))
1056
+ return false;
1057
+ }
1058
+ if (opts.changedOnly && result.content_hash === gradeContentHash(content)) {
1059
+ const metadata = isRecord(document.data.specdojo) ? document.data.specdojo : {};
1060
+ const keys = comparisonSourceKeys(gradedComparisonSources(viewpoints, opts.target, metadata), path, sourceContext);
1061
+ if (keys.length === 0)
1062
+ return false;
1063
+ const current = currentSourceHashes(keys, path, sourceContext);
1064
+ if (!sourceHashesChanged(result.source_hashes, current))
1065
+ return false;
1066
+ }
1067
+ return true;
792
1068
  });
793
1069
  }
1070
+ function currentGradeRubricId(viewpoints) {
1071
+ const id = viewpoints?.grade_rubric?.id;
1072
+ if (typeof id !== "string" || id.length === 0) {
1073
+ throw new Error("--rubric-outdated requires grade_rubric.id in the resolved review viewpoints");
1074
+ }
1075
+ return id;
1076
+ }
1077
+ // 保存済みの結果が現在の rubric 以外で付けられたかを判定する。rubric の記録がない結果は
1078
+ // どの版で付けたか確かめられないため旧版として扱う。結果がない文書は --ungraded の対象である。
1079
+ export function isGradeRubricOutdated(result, currentRubricId) {
1080
+ if (result === undefined)
1081
+ return false;
1082
+ if (typeof result.rubric !== "string" || result.rubric.length === 0)
1083
+ return true;
1084
+ return result.rubric !== currentRubricId;
1085
+ }
794
1086
  function validateGradeTargetFilters(filters) {
795
1087
  if (filters.verdict !== undefined &&
796
1088
  filters.verdict !== "pass" &&
@@ -812,6 +1104,9 @@ function validateGradeTargetFilters(filters) {
812
1104
  filters.maxFindings !== undefined)) {
813
1105
  throw new Error("--ungraded cannot be combined with --verdict, --min-score, or --max-findings");
814
1106
  }
1107
+ if (filters.ungraded && filters.rubricOutdated) {
1108
+ throw new Error("--ungraded cannot be combined with --rubric-outdated");
1109
+ }
815
1110
  }
816
1111
  function storedGradeScore(grade, path) {
817
1112
  const score = grade.score;
@@ -833,6 +1128,12 @@ function storedFindingCount(grade, path) {
833
1128
  }, 0);
834
1129
  }
835
1130
  function matchesParsedGradeTargetFilters(document, path, filters, incomplete = false) {
1131
+ if (filters.dependencyChanged ||
1132
+ filters.rulebookChanged ||
1133
+ filters.unreviewed ||
1134
+ filters.rubricOutdated) {
1135
+ throw new Error("dependencyChanged, rulebookChanged, unreviewed, rubricOutdated cannot be evaluated individually without context");
1136
+ }
836
1137
  const specdojo = document.data.specdojo;
837
1138
  const grade = isRecord(specdojo.grade) ? specdojo.grade : undefined;
838
1139
  if (filters.incomplete && !incomplete)
@@ -857,17 +1158,18 @@ export function matchesGradeTargetFilters(content, path, filters, pipelineState)
857
1158
  const currentState = currentGradePipelineState(document, path, pipelineState);
858
1159
  return matchesParsedGradeTargetFilters(document, path, filters, isIncompleteGradePipelineState(currentState));
859
1160
  }
860
- function continuousViewpoints(doc, target) {
861
- return (doc.viewpoints ?? []).filter((viewpoint) => viewpoint.continuous === true &&
862
- viewpoint.evaluation !== "human" &&
863
- (viewpoint.grade_targets === undefined || viewpoint.grade_targets.includes(target)));
1161
+ // grade の対象は grade_targets と文書の種類(document_kinds)だけで決まる。
1162
+ function gradedViewpoints(doc, target, metadata) {
1163
+ return (doc.viewpoints ?? []).filter((viewpoint) => (viewpoint.grade_targets === undefined || viewpoint.grade_targets.includes(target)) &&
1164
+ viewpointAppliesToDocument(viewpoint, metadata));
864
1165
  }
865
- function agentViewpoints(doc, target) {
866
- return continuousViewpoints(doc, target).filter((viewpoint) => viewpoint.evaluation === "agent");
1166
+ function agentViewpoints(doc, target, metadata) {
1167
+ return gradedViewpoints(doc, target, metadata).filter((viewpoint) => viewpoint.evaluation === "referential" || viewpoint.evaluation === "discretionary");
867
1168
  }
868
1169
  function deterministicResults(document, definitions, target) {
869
1170
  const results = [];
870
- for (const viewpoint of continuousViewpoints(definitions, target).filter((item) => item.evaluation === "deterministic")) {
1171
+ const metadata = document.data.specdojo;
1172
+ for (const viewpoint of gradedViewpoints(definitions, target, metadata).filter((item) => item.evaluation === "deterministic")) {
871
1173
  const findings = [];
872
1174
  const specdojo = document.data.specdojo;
873
1175
  if (viewpoint.id === "vp-arc-document-structure") {
@@ -906,7 +1208,7 @@ function doneCriteriaPlanLines(doneCriteria, definitions) {
906
1208
  return [
907
1209
  "### 3.4. 完了条件(done_criteria)",
908
1210
  "",
909
- "成果物カタログが対象へ宣言する完了条件である。viewpoint と rubric による level 判定とは別の軸として、各条件を現在の本文の根拠だけで `satisfied` / `unsatisfied` のどちらかに判定する。score や level の高低から充足を推論せず、条件文が要求する内容を本文で確認できるかだけで判定する。`roles` は条件の確認責任を持つ Role code、`viewpoint` は条件を見る観点であり、`evaluation: human` の観点に紐づく条件も本文の根拠で一次判定する。",
1211
+ "成果物カタログが対象へ宣言する完了条件である。viewpoint と rubric による level 判定とは別の軸として、各条件を現在の本文の根拠だけで `satisfied` / `unsatisfied` のどちらかに判定する。score や level の高低から充足を推論せず、条件文が要求する内容を本文で確認できるかだけで判定する。`roles` は条件の確認責任を持つ Role code、`viewpoint` は条件を見る観点であり、`evaluation: discretionary` の観点に紐づく条件も本文の根拠で一次判定する。",
910
1212
  "",
911
1213
  ...doneCriteria.map((criterion) => {
912
1214
  const title = titles.get(criterion.viewpoint);
@@ -916,13 +1218,91 @@ function doneCriteriaPlanLines(doneCriteria, definitions) {
916
1218
  "",
917
1219
  ];
918
1220
  }
919
- export function renderGradePlan(opts) {
1221
+ function applicableDoneCriteria(doneCriteria, definitions, metadata) {
1222
+ const viewpoints = new Map((definitions.viewpoints ?? []).map((viewpoint) => [viewpoint.id, viewpoint]));
1223
+ return doneCriteria.filter((criterion) => {
1224
+ const viewpoint = viewpoints.get(criterion.viewpoint);
1225
+ return viewpoint === undefined || viewpointAppliesToDocument(viewpoint, metadata);
1226
+ });
1227
+ }
1228
+ function markdownFence(content) {
1229
+ let longestRun = 0;
1230
+ for (const match of content.matchAll(/`+/g))
1231
+ longestRun = Math.max(longestRun, match[0].length);
1232
+ return "`".repeat(Math.max(3, longestRun + 1));
1233
+ }
1234
+ function splitDocumentForEmbedding(content) {
1235
+ const normalized = content.replace(/\r\n?/g, "\n");
1236
+ const match = normalized.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
1237
+ if (!match)
1238
+ return { body: normalized.replace(/\n$/, "") };
1239
+ return {
1240
+ frontmatter: match[1],
1241
+ body: (match[2] ?? "").replace(/^\n+/, "").replace(/\n$/, ""),
1242
+ };
1243
+ }
1244
+ function renderEmbeddedGradeDocument(path, roles) {
1245
+ const content = readFileSync(resolveSafeRepositoryPath(path, "embedded document"), "utf8");
1246
+ const { frontmatter, body } = splitDocumentForEmbedding(content);
1247
+ const bodyLines = body === "" ? [] : body.split("\n");
1248
+ const numberedBody = bodyLines.map((line, index) => `${index + 1} | ${line}`).join("\n");
1249
+ const lines = [
1250
+ `#### ${roles.join("・")}: \`${path}\``,
1251
+ "",
1252
+ "Frontmatter(`finding.line` の行番号対象外):",
1253
+ "",
1254
+ ];
1255
+ if (frontmatter === undefined) {
1256
+ lines.push("- なし", "");
1257
+ }
1258
+ else {
1259
+ const fence = markdownFence(frontmatter);
1260
+ lines.push(`${fence}yaml`, frontmatter, fence, "");
1261
+ }
1262
+ const bodyFence = markdownFence(numberedBody);
1263
+ lines.push("本文(左端は `finding.line` と同じ、Frontmatter を除く1始まりの行番号):", "", `${bodyFence}text`, numberedBody, bodyFence, "");
1264
+ return lines;
1265
+ }
1266
+ function gradePlanEmbedding(opts) {
1267
+ if (!Number.isSafeInteger(opts.limit) || opts.limit < 1) {
1268
+ throw new Error("maxEmbeddedDocumentCharacters must be a positive integer");
1269
+ }
1270
+ if (!opts.requested) {
1271
+ return { requested: false, embedded: false, characterCount: 0, limit: opts.limit, lines: [] };
1272
+ }
1273
+ const rolesByPath = new Map();
1274
+ const add = (path, role) => {
1275
+ const roles = rolesByPath.get(path);
1276
+ if (roles) {
1277
+ if (!roles.includes(role))
1278
+ roles.push(role);
1279
+ }
1280
+ else {
1281
+ rolesByPath.set(path, [role]);
1282
+ }
1283
+ };
1284
+ add(opts.targetPath, "評価対象");
1285
+ for (const reference of opts.references)
1286
+ add(reference, "参考資料");
1287
+ if (opts.referenceExample)
1288
+ add(opts.referenceExample, "良い実例");
1289
+ const lines = [...rolesByPath].flatMap(([path, roles]) => renderEmbeddedGradeDocument(path, roles));
1290
+ const characterCount = lines.join("\n").length;
1291
+ return {
1292
+ requested: true,
1293
+ embedded: characterCount <= opts.limit,
1294
+ characterCount,
1295
+ limit: opts.limit,
1296
+ lines: characterCount <= opts.limit ? lines : [],
1297
+ };
1298
+ }
1299
+ function renderGradePlanWithEmbedding(opts) {
920
1300
  const rubric = assertRubric(opts.viewpoints);
921
- const viewpoints = agentViewpoints(opts.viewpoints, opts.target);
922
1301
  const absolute = resolveSafeMarkdownPath(opts.path);
923
1302
  const rel = repoRelativePath(absolute);
924
1303
  const document = parseMarkdown(readFileSync(absolute, "utf8"), rel);
925
1304
  const metadata = document.data.specdojo;
1305
+ const viewpoints = agentViewpoints(opts.viewpoints, opts.target, metadata);
926
1306
  const documentId = typeof metadata.id === "string" ? metadata.id : rel;
927
1307
  const priorFindings = (opts.resultsDirectory
928
1308
  ? readGradeResult(gradeResultPath(opts.resultsDirectory, documentId))
@@ -933,7 +1313,16 @@ export function renderGradePlan(opts) {
933
1313
  const referenceExample = opts.referenceExample
934
1314
  ? repoRelativePath(resolveSafeMarkdownPath(opts.referenceExample))
935
1315
  : undefined;
936
- const doneCriteria = opts.target === "deliverable" ? (opts.doneCriteria ?? []) : [];
1316
+ const embedding = gradePlanEmbedding({
1317
+ requested: opts.embedDocuments ?? false,
1318
+ targetPath: rel,
1319
+ references,
1320
+ referenceExample,
1321
+ limit: opts.maxEmbeddedDocumentCharacters ?? GRADE_PLAN_EMBEDDED_DOCUMENT_CHARACTER_LIMIT,
1322
+ });
1323
+ const doneCriteria = opts.target === "deliverable"
1324
+ ? applicableDoneCriteria(opts.doneCriteria ?? [], opts.viewpoints, metadata)
1325
+ : [];
937
1326
  const lines = [
938
1327
  "---",
939
1328
  yaml
@@ -955,7 +1344,7 @@ export function renderGradePlan(opts) {
955
1344
  "",
956
1345
  `# Review Plan: ${taskId} grade: ${rel}`,
957
1346
  "",
958
- "この plan は grade pipeline の executor stage 用である。評価と根拠の記述だけを行い、GradeSubmission JSON は作成しない。後続の reporter が判定内容を変更せず JSON へ構造化する。",
1347
+ "この plan は grade pipeline の executor stage 用である。評価と根拠の記述だけを行い、GradeSubmission JSON は作成しない。`grade apply` が最終応答の marker を機械的に解析して GradeSubmission を生成し、契約を満たさない応答は拒否して executor を再実行する。",
959
1348
  "",
960
1349
  "## 1. このタスクで行うこと",
961
1350
  "",
@@ -986,18 +1375,42 @@ export function renderGradePlan(opts) {
986
1375
  "",
987
1376
  ]
988
1377
  : []),
1378
+ ...(embedding.embedded
1379
+ ? [
1380
+ "### 埋め込み資料",
1381
+ "",
1382
+ `評価対象・参考資料・良い実例を plan 生成時点の内容で埋め込む。埋め込み部分は ${embedding.characterCount.toLocaleString("en-US")} 文字(上限 ${embedding.limit.toLocaleString("en-US")} 文字)である。`,
1383
+ "",
1384
+ ...embedding.lines,
1385
+ ]
1386
+ : embedding.requested
1387
+ ? [
1388
+ "### 埋め込み資料",
1389
+ "",
1390
+ `警告: 埋め込み部分が ${embedding.characterCount.toLocaleString("en-US")} 文字となり、上限 ${embedding.limit.toLocaleString("en-US")} 文字を超えたため、本文を埋め込まずパス参照へフォールバックした。`,
1391
+ "",
1392
+ ]
1393
+ : []),
989
1394
  "## 3. 進め方",
990
1395
  "",
991
- "1. 評価対象をファイル読み取りツールで全文読み、実行ログに読み取り操作を残す。plan に対象本文は埋め込まれていないため、この手順を省略しない。",
992
- "2. 参考資料と良い実例がある場合は列挙された全ファイルを全文読み、実行ログに各パスの読み取り操作を残す。参考資料や良い実例を評価対象と混同しない。",
1396
+ ...(embedding.embedded
1397
+ ? [
1398
+ "1. plan の「埋め込み資料」にある評価対象の本文を全文読む。Frontmatter は行番号の対象外であり、本文左端の番号を finding の `line` に使う。",
1399
+ "2. 埋め込まれた参考資料と良い実例がある場合はすべて読む。ファイル読み取りツールと検索ツールを使わず、plan に埋め込まれた資料だけで判定し、参考資料や良い実例を評価対象と混同しない。",
1400
+ ]
1401
+ : [
1402
+ "1. 評価対象をファイル読み取りツールで全文読み、実行ログに読み取り操作を残す。plan に対象本文は埋め込まれていないため、この手順を省略しない。",
1403
+ "2. 参考資料と良い実例がある場合は列挙された全ファイルを全文読み、実行ログに各パスの読み取り操作を残す。参考資料や良い実例を評価対象と混同しない。",
1404
+ ]),
993
1405
  "3. 良い実例がある場合は、章ごとの具体性、根拠の密度、過不足を評価対象と比較して記載水準を判定する。表現の類似や実例自体の欠点を評価理由にせず、rubric と viewpoint を最終的な判定基準にする。",
994
1406
  "4. 評価対象を次の rubric と viewpoint に照らし、各 viewpoint を 0-4 で判定する。ある viewpoint の finding の有無から、ほかの viewpoint の判定を推論しない。",
995
- "5. level 3 以下には finding を付ける。finding には severity(blocker / major / minor / note)、対象直前の本文行番号、具体的な修正理由を含める。line は Frontmatter を除く本文の1始まり(通常は H1 が1行目)とする。level 4 は finding なしとする。",
996
- "6. 前回の指摘を対象の現在内容と照合し、解消済みか確認する。未解消なら前回の message を変更せず今回の finding に含め、severity は前回と同等以上を指定する。前回の rule は前回評価時の分類として扱い、各 viewpoint は現在の根拠から独立に評価する。前回の問題が解消され、別の軽微な問題だけが残るため severity を引き下げる場合は、その根拠を新しい finding の message に含める。",
997
- "7. 前回の指摘の確認だけで終了せず、前回の指摘にない問題もすべての viewpoint で独立して検出する。",
1407
+ "5. 判定根拠と新しい finding の message は英語で記述する。固有名詞・識別子・引用は原文を保ってよい。日本語だけの既存 finding は互換用の正本として扱い、未解消ならその message を翻訳せず原文のまま再掲する。",
1408
+ "6. level 3 以下には finding を付ける。finding には severity(blocker / major / minor / note)、対象直前の本文行番号、具体的な修正理由を含める。line は Frontmatter を除く本文の1始まり(通常は H1 が1行目)とする。level 4 は finding なしとする。",
1409
+ "7. 前回の指摘を対象の現在内容と照合し、解消済みか確認する。未解消なら前回の canonical message を変更せず今回の finding に含め、severity は前回と同等以上を指定する。前回の rule は前回評価時の分類として扱い、各 viewpoint は現在の根拠から独立に評価する。前回の問題が解消され、別の軽微な問題だけが残るため severity を引き下げる場合は、その根拠を新しい finding の message に含める。",
1410
+ "8. 前回の指摘の確認だけで終了せず、前回の指摘にない問題もすべての viewpoint で独立して検出する。",
998
1411
  ...(doneCriteria.length > 0
999
1412
  ? [
1000
- "8. 完了条件(done_criteria)を1件ずつ本文の根拠と照合し、`satisfied` / `unsatisfied` を判定する。viewpoint の level や総合 score とは独立した判定であり、level が高いことを理由に条件を満たしたとみなさない。`unsatisfied` には不足している内容を1行で記す。",
1413
+ "9. 完了条件(done_criteria)を1件ずつ本文の根拠と照合し、`satisfied` / `unsatisfied` を判定する。viewpoint の level や総合 score とは独立した判定であり、level が高いことを理由に条件を満たしたとみなさない。`unsatisfied` には不足している内容を英語で1行に記す。",
1001
1414
  ]
1002
1415
  : []),
1003
1416
  "",
@@ -1033,7 +1446,7 @@ export function renderGradePlan(opts) {
1033
1446
  "",
1034
1447
  "1. すべての agent viewpoint の判定と、必要な finding が揃っていることを確認する。",
1035
1448
  "2. 最終応答では各 viewpoint を次のマーカーで1回ずつ宣言する。マーカー間には根拠や検討過程を自由形式で詳しく記述してよい。JSON、Markdown コードフェンス、GradeSubmission は出力しない。",
1036
- "3. `LEVEL` と各 `FINDING` は reporter が忠実性を機械検証する申告値である。message は1行で具体的に記し、reporter が一字一句コピーできるようにする。finding がない場合は `FINDING` 行を記さない。",
1449
+ "3. `LEVEL` と各 `FINDING` は `grade apply` が機械的に読み取る申告値である。marker・`LEVEL`・`FINDING` はそれぞれ行頭に1行で記し、message は英語で1行に具体的に記す。message は正本としてそのまま記録される。finding がない場合は `FINDING` 行を記さない。",
1037
1450
  "4. すべての viewpoint marker、0-4 の level、level 3 以下の finding、severity と非空 message が揃っていることを確認する。",
1038
1451
  ...(doneCriteria.length > 0
1039
1452
  ? [
@@ -1062,26 +1475,35 @@ export function renderGradePlan(opts) {
1062
1475
  "",
1063
1476
  "## 5. 異常終了の条件",
1064
1477
  "",
1065
- "- 評価対象、参考資料、または良い実例を読み取れない場合は、内容を推測せず異常終了する。",
1478
+ ...(embedding.embedded
1479
+ ? [
1480
+ "- plan に評価対象、参考資料、または良い実例の埋め込み内容が欠けている場合は、内容を推測せず異常終了する。",
1481
+ ]
1482
+ : ["- 評価対象、参考資料、または良い実例を読み取れない場合は、内容を推測せず異常終了する。"]),
1066
1483
  "- rubric または viewpoint に不足があり、全項目を判定できない場合は異常終了する。",
1067
1484
  "- すべての viewpoint の level と finding を申告できない場合は異常終了する。",
1068
1485
  ...(doneCriteria.length > 0
1069
1486
  ? ["- 列挙された完了条件のいずれかを判定できない場合は異常終了する。"]
1070
1487
  : []),
1071
1488
  ];
1072
- return `${lines.join("\n")}\n`;
1489
+ return { content: `${lines.join("\n")}\n`, embedding };
1490
+ }
1491
+ export function renderGradePlan(opts) {
1492
+ return renderGradePlanWithEmbedding(opts).content;
1073
1493
  }
1074
1494
  export function renderGradeReporterPlan(opts) {
1075
1495
  const rubric = assertRubric(opts.viewpoints);
1076
- const viewpoints = agentViewpoints(opts.viewpoints, opts.target);
1077
1496
  const absolute = resolveSafeMarkdownPath(opts.path);
1078
1497
  const rel = repoRelativePath(absolute);
1079
1498
  const document = parseMarkdown(readFileSync(absolute, "utf8"), rel);
1080
1499
  const metadata = document.data.specdojo;
1500
+ const viewpoints = agentViewpoints(opts.viewpoints, opts.target, metadata);
1081
1501
  const documentId = typeof metadata.id === "string" ? metadata.id : rel;
1082
1502
  const taskHash = createHash("sha256").update(rel).digest("hex").slice(0, 12).toUpperCase();
1083
1503
  const taskId = `GRADE-${opts.target.toUpperCase()}-${taskHash}-REPORTER`;
1084
- const doneCriteria = opts.target === "deliverable" ? (opts.doneCriteria ?? []) : [];
1504
+ const doneCriteria = opts.target === "deliverable"
1505
+ ? applicableDoneCriteria(opts.doneCriteria ?? [], opts.viewpoints, metadata)
1506
+ : [];
1085
1507
  const lines = [
1086
1508
  "---",
1087
1509
  yaml
@@ -1103,7 +1525,7 @@ export function renderGradeReporterPlan(opts) {
1103
1525
  "",
1104
1526
  `# Reporter Plan: ${taskId} grade: ${rel}`,
1105
1527
  "",
1106
- "この plan は grade pipeline の reporter stage 用である。executor の最終応答が `<grade_executor_output>` としてこの plan と一緒に渡される。評価やファイル読み取りは行わず、申告済みの判定を GradeSubmission JSON へ忠実に構造化する。",
1528
+ "この plan は grade pipeline の reporter stage 用である。既定の pipeline は reporter を起動せず、`grade apply` が executor の marker から GradeSubmission を機械的に生成する。この plan は LLM reporter を明示指定して書き写しの精度を比較・検証する場合にだけ使う。executor の最終応答が `<grade_executor_output>` としてこの plan と一緒に渡される。評価やファイル読み取りは行わず、申告済みの判定を GradeSubmission JSON へ忠実に構造化する。",
1107
1529
  "",
1108
1530
  "## 1. このタスクで行うこと",
1109
1531
  "",
@@ -1121,7 +1543,7 @@ export function renderGradeReporterPlan(opts) {
1121
1543
  "1. `<grade_executor_output>` の `[VIEWPOINT <id>]` ごとに `LEVEL` とすべての `FINDING` を読み取る。対象文書や参考資料は読まない。",
1122
1544
  "2. level、severity、line、message を executor の申告どおりにコピーする。message の要約、言い換え、校正を行わない。",
1123
1545
  "3. executor が述べていない finding を追加せず、述べた finding を省略しない。finding の `id` は出力しない。",
1124
- "4. marker が欠けている、値が曖昧、または GradeSubmission の検証規則と矛盾する場合は推測せず異常終了する。",
1546
+ "4. finding の severity により viewpoint の level に上限がある(`blocker` は上限 0、`major` は上限 2、`minor` は上限 3)。executor の申告が上限を超えていても level は申告どおりにコピーし、補正は `grade apply` に委ねる。marker 欠落など、それ以外の GradeSubmission 契約違反は推測で補わず異常終了する。",
1125
1547
  ...(doneCriteria.length > 0
1126
1548
  ? [
1127
1549
  "5. `[DONE_CRITERIA]` ブロックの各行を `done_criteria` へ写す。`id` と `status`(`satisfied` / `unsatisfied`)は申告どおりにコピーし、`unsatisfied` に続く不足内容は `reason` へ一字一句コピーする。条件の追加・省略・判定変更を行わない。",
@@ -1168,7 +1590,7 @@ export function renderGradeReporterPlan(opts) {
1168
1590
  "## 5. 異常終了の条件",
1169
1591
  "",
1170
1592
  "- `<grade_executor_output>` が渡されていない、または marker 契約を解析できない場合は異常終了する。",
1171
- "- executor の申告を変更しなければ GradeSubmission の契約を満たせない場合は異常終了する。",
1593
+ "- level の下方向補正を除き、executor の申告を変更しなければ GradeSubmission の契約を満たせない場合は異常終了する。",
1172
1594
  ];
1173
1595
  return `${lines.join("\n")}\n`;
1174
1596
  }
@@ -1206,7 +1628,7 @@ export function writeGradePlans(opts) {
1206
1628
  random: opts.random,
1207
1629
  });
1208
1630
  const doneCriteria = opts.doneCriteriaByPath?.get(repoRelativePath(absolute));
1209
- const content = renderGradePlan({
1631
+ const rendered = renderGradePlanWithEmbedding({
1210
1632
  target: opts.target,
1211
1633
  path: absolute,
1212
1634
  references: resolveGradeReferencePathsFromCatalog(absolute, kataReferences),
@@ -1214,7 +1636,9 @@ export function writeGradePlans(opts) {
1214
1636
  viewpoints: opts.viewpoints,
1215
1637
  projectId: opts.projectId,
1216
1638
  doneCriteria,
1639
+ embedDocuments: opts.embedDocuments,
1217
1640
  });
1641
+ const content = rendered.content;
1218
1642
  const reporterContent = renderGradeReporterPlan({
1219
1643
  target: opts.target,
1220
1644
  path: absolute,
@@ -1235,15 +1659,34 @@ export function writeGradePlans(opts) {
1235
1659
  reporterChanged,
1236
1660
  target: repoRelativePath(absolute),
1237
1661
  referenceExample,
1662
+ documentsEmbedded: rendered.embedding.embedded,
1663
+ embeddingCharacterCount: rendered.embedding.characterCount,
1664
+ embeddingCharacterLimit: rendered.embedding.limit,
1238
1665
  };
1239
1666
  });
1240
1667
  }
1668
+ // executor の最終応答に現れる marker 行の軽微な書式の揺れを正規化する。受理するのは、行頭の
1669
+ // 空白、ブロッククオート `>`、リスト記号(`-` / `*` / `+` と空白)、および marker・LEVEL・
1670
+ // FINDING・DC-NNN の見出し部分を囲む `**` だけである。message と reason の本文は変更しない。
1671
+ // 文中に埋もれた FINDING などは marker とみなさず、従来どおり無視または拒否する。
1672
+ export function normalizeGradeExecutorLine(line) {
1673
+ let normalized = line.replace(/^\s*(?:>\s*)*(?:[-*+]\s+)?/, "");
1674
+ const wrappedMarker = normalized.match(/^\*\*(\[(?:END )?(?:VIEWPOINT[^\]]*|DONE_CRITERIA)\])\*\*\s*$/);
1675
+ if (wrappedMarker)
1676
+ return wrappedMarker[1];
1677
+ const wrappedLevel = normalized.match(/^\*\*(LEVEL:\s*[0-4])\*\*\s*$/);
1678
+ if (wrappedLevel)
1679
+ return wrappedLevel[1];
1680
+ normalized = normalized.replace(/^\*\*(LEVEL|FINDING(?:\s+[a-z]+)?(?:\s+line=[0-9]+)?|DC-[0-9]{3,})(:?)\*\*(:?)/, (_match, head, innerColon, outerColon) => `${head}${innerColon}${outerColon}`);
1681
+ return normalized;
1682
+ }
1241
1683
  export function parseGradeExecutorAnalysis(raw) {
1242
1684
  const viewpoints = [];
1243
1685
  let doneCriteria;
1244
1686
  let inDoneCriteria = false;
1245
1687
  let current;
1246
- for (const [lineIndex, line] of raw.split(/\r?\n/).entries()) {
1688
+ for (const [lineIndex, rawLine] of raw.split(/\r?\n/).entries()) {
1689
+ const line = normalizeGradeExecutorLine(rawLine);
1247
1690
  if (/^\[DONE_CRITERIA\]\s*$/.test(line)) {
1248
1691
  if (current)
1249
1692
  throw new Error(`line ${lineIndex + 1}: DONE_CRITERIA inside VIEWPOINT`);
@@ -1427,34 +1870,58 @@ function doneCriteriaFidelityIssues(declared, reported) {
1427
1870
  }
1428
1871
  return issues;
1429
1872
  }
1430
- export function validateGradeReporterFidelity(opts) {
1873
+ // executor の marker を parse し、GradeSubmission へ機械的に変換したうえで既存の
1874
+ // GradeSubmission 検証にかける。severity が定める上限より level が高い場合は、判定を甘くしない
1875
+ // 方向へ level だけを補正し、補正前後を submission に残す。それ以外の marker 契約違反と
1876
+ // done_criteria の過不足は拒否する。
1877
+ function convertGradeExecutorOutput(opts) {
1431
1878
  let analysis;
1432
1879
  try {
1433
1880
  analysis = parseGradeExecutorAnalysis(opts.executorOutput);
1434
1881
  }
1435
1882
  catch (error) {
1436
- return [
1437
- {
1438
- path: "$analysis",
1439
- message: error instanceof Error ? error.message : String(error),
1440
- },
1441
- ];
1883
+ return {
1884
+ issues: [
1885
+ {
1886
+ path: "$analysis",
1887
+ message: error instanceof Error ? error.message : String(error),
1888
+ },
1889
+ ],
1890
+ };
1442
1891
  }
1443
1892
  const rubric = assertRubric(opts.viewpoints);
1444
- const analysisIssues = validateGradeSubmission({
1893
+ const corrected = correctViewpointLevels(analysis.viewpoints);
1894
+ const submission = {
1445
1895
  rubric: rubric.id,
1446
1896
  documents: [
1447
1897
  {
1448
1898
  path: opts.expectedPath,
1449
- viewpoints: analysis.viewpoints,
1899
+ viewpoints: corrected.viewpoints,
1900
+ ...(corrected.corrections.length > 0 ? { level_corrections: corrected.corrections } : {}),
1450
1901
  ...(analysis.doneCriteria ? { done_criteria: analysis.doneCriteria } : {}),
1451
1902
  },
1452
1903
  ],
1453
- }, opts.viewpoints, opts.target, opts.doneCriteria
1904
+ };
1905
+ const issues = validateGradeSubmission(submission, opts.viewpoints, opts.target, opts.doneCriteria
1454
1906
  ? { doneCriteriaByPath: new Map([[opts.expectedPath, opts.doneCriteria]]) }
1455
1907
  : {}).map((issue) => ({ path: `$analysis.${issue.path}`, message: issue.message }));
1456
- if (analysisIssues.length > 0)
1457
- return analysisIssues;
1908
+ if (issues.length > 0)
1909
+ return { issues };
1910
+ return { analysis, submission, issues: [] };
1911
+ }
1912
+ // executor の分析から GradeSubmission を生成する。LLM の reporter を通さずに grade を記録する
1913
+ // 既定の経路で使う。拒否時は issues を返し、呼び出し側は executor を再実行する。
1914
+ export function buildGradeSubmissionFromAnalysis(opts) {
1915
+ const conversion = convertGradeExecutorOutput(opts);
1916
+ if (conversion.submission === undefined)
1917
+ return { issues: conversion.issues };
1918
+ return { submission: conversion.submission, issues: [] };
1919
+ }
1920
+ export function validateGradeReporterFidelity(opts) {
1921
+ const conversion = convertGradeExecutorOutput(opts);
1922
+ if (conversion.analysis === undefined)
1923
+ return conversion.issues;
1924
+ const analysis = conversion.analysis;
1458
1925
  if (opts.submission.documents.length !== 1) {
1459
1926
  return [
1460
1927
  { path: "documents", message: "reporter submission must contain exactly one document" },
@@ -1592,8 +2059,6 @@ export function validateGradeSubmission(submission, doc, target, options = {}) {
1592
2059
  const rubric = assertRubric(doc);
1593
2060
  if (submission.rubric !== rubric.id)
1594
2061
  issues.push({ path: "$", message: `rubric must be ${rubric.id}` });
1595
- const required = agentViewpoints(doc, target);
1596
- const allowed = new Map(required.map((viewpoint) => [viewpoint.id, viewpoint]));
1597
2062
  const paths = new Set();
1598
2063
  for (const [documentIndex, document] of submission.documents.entries()) {
1599
2064
  const where = `documents[${documentIndex}]`;
@@ -1604,13 +2069,23 @@ export function validateGradeSubmission(submission, doc, target, options = {}) {
1604
2069
  if (paths.has(document.path))
1605
2070
  issues.push({ path: where, message: `duplicate path: ${document.path}` });
1606
2071
  paths.add(document.path);
1607
- const normalizedDocumentPath = repoRelativePath(resolve(specdojoRootDir(), document.path));
2072
+ const absoluteDocumentPath = resolve(specdojoRootDir(), document.path);
2073
+ const normalizedDocumentPath = repoRelativePath(absoluteDocumentPath);
2074
+ const metadata = existsSync(absoluteDocumentPath)
2075
+ ? parseMarkdown(readFileSync(absoluteDocumentPath, "utf8"), normalizedDocumentPath).data
2076
+ .specdojo
2077
+ : {};
2078
+ const required = agentViewpoints(doc, target, metadata);
2079
+ const allowed = new Map(required.map((viewpoint) => [viewpoint.id, viewpoint]));
2080
+ const expectedDoneCriteria = options.doneCriteriaByPath?.get(document.path) ??
2081
+ options.doneCriteriaByPath?.get(normalizedDocumentPath);
1608
2082
  issues.push(...validateDoneCriteriaInput({
1609
2083
  where,
1610
2084
  target,
1611
2085
  value: document.done_criteria,
1612
- expected: options.doneCriteriaByPath?.get(document.path) ??
1613
- options.doneCriteriaByPath?.get(normalizedDocumentPath),
2086
+ expected: expectedDoneCriteria
2087
+ ? applicableDoneCriteria(expectedDoneCriteria, doc, metadata)
2088
+ : undefined,
1614
2089
  }));
1615
2090
  const ids = new Set();
1616
2091
  const findingIds = new Set();
@@ -1619,7 +2094,7 @@ export function validateGradeSubmission(submission, doc, target, options = {}) {
1619
2094
  if (!result || !allowed.has(result.id)) {
1620
2095
  issues.push({
1621
2096
  path: resultPath,
1622
- message: `unknown or non-continuous viewpoint: ${result?.id ?? ""}`,
2097
+ message: `unknown or non-applicable viewpoint: ${result?.id ?? ""}`,
1623
2098
  });
1624
2099
  continue;
1625
2100
  }
@@ -1648,6 +2123,13 @@ export function validateGradeSubmission(submission, doc, target, options = {}) {
1648
2123
  });
1649
2124
  continue;
1650
2125
  }
2126
+ if (finding.message_ja !== undefined &&
2127
+ (typeof finding.message_ja !== "string" || !finding.message_ja.trim())) {
2128
+ issues.push({
2129
+ path: `${resultPath}.findings[${findingIndex}].message_ja`,
2130
+ message: "message_ja must be a non-empty string when present",
2131
+ });
2132
+ }
1651
2133
  if (finding.id !== undefined) {
1652
2134
  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(finding.id)) {
1653
2135
  issues.push({
@@ -1674,6 +2156,31 @@ export function validateGradeSubmission(submission, doc, target, options = {}) {
1674
2156
  if (result.level > cap)
1675
2157
  issues.push({ path: resultPath, message: `finding severity caps level at ${cap}` });
1676
2158
  }
2159
+ if (document.level_corrections !== undefined) {
2160
+ if (!Array.isArray(document.level_corrections)) {
2161
+ issues.push({ path: `${where}.level_corrections`, message: "must be an array" });
2162
+ }
2163
+ else {
2164
+ for (const [index, correction] of document.level_corrections.entries()) {
2165
+ const correctedViewpoint = document.viewpoints.find((viewpoint) => viewpoint.id === correction?.viewpoint);
2166
+ if (!correction ||
2167
+ typeof correction.viewpoint !== "string" ||
2168
+ !correctedViewpoint ||
2169
+ !Number.isInteger(correction.original_level) ||
2170
+ !Number.isInteger(correction.corrected_level) ||
2171
+ correction.original_level < 0 ||
2172
+ correction.original_level > 4 ||
2173
+ correction.corrected_level < 0 ||
2174
+ correction.corrected_level >= correction.original_level ||
2175
+ correctedViewpoint.level !== correction.corrected_level) {
2176
+ issues.push({
2177
+ path: `${where}.level_corrections[${index}]`,
2178
+ message: "viewpoint and matching downward original/corrected levels from 0 to 4 are required",
2179
+ });
2180
+ }
2181
+ }
2182
+ }
2183
+ }
1677
2184
  for (const viewpoint of required) {
1678
2185
  if (!ids.has(viewpoint.id)) {
1679
2186
  issues.push({ path: where, message: `missing agent viewpoint: ${viewpoint.id}` });
@@ -1743,6 +2250,9 @@ export function applyGradeSubmission(opts) {
1743
2250
  if (issues.length > 0)
1744
2251
  throw new Error(issues.map((issue) => `${issue.path}: ${issue.message}`).join("\n"));
1745
2252
  const changed = [];
2253
+ const sourceContext = opts.resultsDirectory
2254
+ ? createGradeSourceContext(opts.project, specdojoRootDir())
2255
+ : undefined;
1746
2256
  for (const input of opts.submission.documents) {
1747
2257
  const absolute = resolveSafeMarkdownPath(input.path);
1748
2258
  const rel = repoRelativePath(absolute);
@@ -1760,6 +2270,22 @@ export function applyGradeSubmission(opts) {
1760
2270
  const previous = readGradeResult(resultPath);
1761
2271
  const document = parseMarkdown(current, rel);
1762
2272
  const agentResults = preserveStoredFindingSeverities(previous, input.viewpoints);
2273
+ const correctionByViewpoint = new Map((input.level_corrections ?? []).map((correction) => [
2274
+ correction.viewpoint,
2275
+ { ...correction },
2276
+ ]));
2277
+ for (const [index, result] of agentResults.entries()) {
2278
+ const submitted = input.viewpoints[index];
2279
+ if (submitted && result.level < submitted.level) {
2280
+ const existing = correctionByViewpoint.get(result.id);
2281
+ correctionByViewpoint.set(result.id, {
2282
+ viewpoint: result.id,
2283
+ original_level: existing?.original_level ?? submitted.level,
2284
+ corrected_level: result.level,
2285
+ });
2286
+ }
2287
+ }
2288
+ const levelCorrections = [...correctionByViewpoint.values()];
1763
2289
  const evaluated = {
1764
2290
  ...input,
1765
2291
  viewpoints: [
@@ -1790,12 +2316,16 @@ export function applyGradeSubmission(opts) {
1790
2316
  line,
1791
2317
  anchor: bodyLines[Math.min(bodyLines.length, line) - 1]?.trim() ?? "",
1792
2318
  message: sanitizeCommentText(finding.message),
2319
+ message_ja: sanitizeCommentText(finding.message_ja ?? finding.message),
1793
2320
  };
1794
2321
  }));
1795
2322
  const criteriaResults = opts.target === "deliverable" && definitions && input.done_criteria && detailPath
1796
2323
  ? input.done_criteria
1797
2324
  : undefined;
1798
2325
  const detailRef = criteriaResults ? doneCriteriaDetailId(documentId, absolute) : undefined;
2326
+ const sourceHashes = sourceContext
2327
+ ? gradeSourceHashes(absolute, document, opts.viewpoints, opts.target, sourceContext)
2328
+ : undefined;
1799
2329
  const result = {
1800
2330
  version: 1,
1801
2331
  document: documentId,
@@ -1808,10 +2338,14 @@ export function applyGradeSubmission(opts) {
1808
2338
  graded_at: gradedAt,
1809
2339
  graded_by: opts.gradedBy,
1810
2340
  content_hash: gradeContentHash(current),
2341
+ ...(sourceHashes && Object.keys(sourceHashes).length > 0
2342
+ ? { source_hashes: sourceHashes }
2343
+ : {}),
1811
2344
  categories: summary.categories,
1812
2345
  viewpoints: summary.viewpoints,
1813
2346
  finding_counts: summary.findings,
1814
2347
  findings,
2348
+ ...(levelCorrections.length > 0 ? { level_corrections: levelCorrections } : {}),
1815
2349
  ...(criteriaResults && definitions && detailRef
1816
2350
  ? { done_criteria: summarizeDoneCriteria(definitions, criteriaResults, detailRef) }
1817
2351
  : {}),
@@ -1939,6 +2473,9 @@ export function gradeMarkdownDocument(opts) {
1939
2473
  const criteriaResults = opts.target === "deliverable" && opts.doneCriteria && opts.input.done_criteria
1940
2474
  ? opts.input.done_criteria
1941
2475
  : undefined;
2476
+ const applicableCriteriaDefinitions = opts.doneCriteria
2477
+ ? applicableDoneCriteria(opts.doneCriteria.definitions, opts.viewpoints, specdojo)
2478
+ : undefined;
1942
2479
  specdojo.grade = {
1943
2480
  rubric: rubric.id,
1944
2481
  ...(opts.reference ? { reference: resolveGradeReferenceId(opts.reference) } : {}),
@@ -1951,9 +2488,9 @@ export function gradeMarkdownDocument(opts) {
1951
2488
  categories: summary.categories,
1952
2489
  viewpoints: summary.viewpoints,
1953
2490
  findings: summary.findings,
1954
- ...(criteriaResults && opts.doneCriteria
2491
+ ...(criteriaResults && opts.doneCriteria && applicableCriteriaDefinitions
1955
2492
  ? {
1956
- done_criteria: summarizeDoneCriteria(opts.doneCriteria.definitions, criteriaResults, opts.doneCriteria.detailRef),
2493
+ done_criteria: summarizeDoneCriteria(applicableCriteriaDefinitions, criteriaResults, opts.doneCriteria.detailRef),
1957
2494
  }
1958
2495
  : {}),
1959
2496
  };
@@ -2080,6 +2617,7 @@ export function migrateInlineGrades(opts) {
2080
2617
  const findings = legacyFindings.map((finding) => ({
2081
2618
  ...finding,
2082
2619
  anchor: bodyLines[Math.min(bodyLines.length, finding.line) - 1]?.trim() ?? "",
2620
+ message_ja: finding.message,
2083
2621
  }));
2084
2622
  const counts = { blocker: 0, major: 0, minor: 0, note: 0 };
2085
2623
  for (const finding of findings)
@@ -2155,6 +2693,13 @@ function requirePositiveInteger(value) {
2155
2693
  }
2156
2694
  return parsed;
2157
2695
  }
2696
+ function requireNonNegativeInteger(value) {
2697
+ const parsed = Number(value);
2698
+ if (!Number.isSafeInteger(parsed) || parsed < 0) {
2699
+ throw new Error("value must be a non-negative integer");
2700
+ }
2701
+ return parsed;
2702
+ }
2158
2703
  function requirePipelineStatus(value) {
2159
2704
  if (value !== "passed" && value !== "failed" && value !== "complete") {
2160
2705
  throw new Error("--status must be passed, failed, or complete");
@@ -2165,6 +2710,19 @@ function commandError(error) {
2165
2710
  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
2166
2711
  process.exitCode = 1;
2167
2712
  }
2713
+ export function renderGradeFindingTranslationPlan(result, translationIndex) {
2714
+ const messages = gradeFindingTranslationInput(result, translationIndex);
2715
+ return [
2716
+ "# Grade finding translation",
2717
+ "",
2718
+ "次の JSON 文字列配列に含まれる英語の finding だけを、簡潔で自然な日本語へ翻訳してください。入力と同じ件数・同じ順序の、訳文だけの JSON 文字列配列を返してください。元の文にあるインラインコード(バッククォートで囲んだ部分)は一字一句変えずに残し、元の文にないインラインコードやバッククォートは追加しないでください。インラインコード以外の英語の語句は、固有名詞・識別子を除いて日本語に訳してください。Markdown fence、説明、番号、token、判定の変更は不要です。",
2719
+ "",
2720
+ "```json",
2721
+ JSON.stringify(messages, null, 2),
2722
+ "```",
2723
+ "",
2724
+ ].join("\n");
2725
+ }
2168
2726
  export function registerGradeCommand(program) {
2169
2727
  const grade = program
2170
2728
  .command("grade")
@@ -2174,11 +2732,15 @@ export function registerGradeCommand(program) {
2174
2732
  .option("--project <projectId>", "Project id in specdojo.config.json")
2175
2733
  .option("--path <path>", "Grade only this Markdown document (repeatable)", collectPathOption, [])
2176
2734
  .option("--changed-only", "Select documents changed since their latest grade", false)
2735
+ .option("--dependency-changed", "Select documents whose dependencies have been graded more recently", false)
2736
+ .option("--rulebook-changed", "Select documents whose declared rulebook has been graded more recently", false)
2737
+ .option("--unreviewed", "Select ungraded or changed documents that do not have a schedule task", false)
2177
2738
  .option("--verdict <verdict>", "Select documents with this latest verdict: pass, needs-work, or fail", requireGradeVerdict)
2178
2739
  .option("--min-score <score>", "Select graded documents with at least this score (0-100)", requireMinScore)
2179
2740
  .option("--max-findings <count>", "Select graded documents with at most this many findings", requireMaxFindings)
2180
2741
  .option("--ungraded", "Select documents without a stored grade", false)
2181
- .option("--incomplete", "Select documents with a retryable incomplete pipeline", false);
2742
+ .option("--incomplete", "Select documents with a retryable incomplete pipeline", false)
2743
+ .option("--rubric-outdated", "Select graded documents whose stored result was not graded with the current rubric", false);
2182
2744
  addSelection(grade.command("list").description("Print selected document paths without writing grade plans")).action((options) => {
2183
2745
  try {
2184
2746
  const paths = discoverGradeTargets({
@@ -2186,11 +2748,15 @@ export function registerGradeCommand(program) {
2186
2748
  project: options.project,
2187
2749
  paths: options.path,
2188
2750
  changedOnly: options.changedOnly,
2751
+ dependencyChanged: options.dependencyChanged,
2752
+ rulebookChanged: options.rulebookChanged,
2753
+ unreviewed: options.unreviewed,
2189
2754
  verdict: options.verdict,
2190
2755
  minScore: options.minScore,
2191
2756
  maxFindings: options.maxFindings,
2192
2757
  ungraded: options.ungraded,
2193
2758
  incomplete: options.incomplete,
2759
+ rubricOutdated: options.rubricOutdated,
2194
2760
  });
2195
2761
  for (const path of paths)
2196
2762
  process.stdout.write(`${repoRelativePath(path)}\n`);
@@ -2204,6 +2770,7 @@ export function registerGradeCommand(program) {
2204
2770
  .description("Write reusable executor and reporter plans per selected document"))
2205
2771
  .option("--out <directory>", "Write plans below this repository-relative directory")
2206
2772
  .option("--reference <path>", "Use this document as the comparison reference")
2773
+ .option("--embed-documents", "Embed the target and reference documents in the executor plan", false)
2207
2774
  .option("--random-reference", "Select a comparison reference at random from ready documents", false)
2208
2775
  .action((options) => {
2209
2776
  try {
@@ -2215,11 +2782,15 @@ export function registerGradeCommand(program) {
2215
2782
  project: options.project,
2216
2783
  paths: options.path,
2217
2784
  changedOnly: options.changedOnly,
2785
+ dependencyChanged: options.dependencyChanged,
2786
+ rulebookChanged: options.rulebookChanged,
2787
+ unreviewed: options.unreviewed,
2218
2788
  verdict: options.verdict,
2219
2789
  minScore: options.minScore,
2220
2790
  maxFindings: options.maxFindings,
2221
2791
  ungraded: options.ungraded,
2222
2792
  incomplete: options.incomplete,
2793
+ rubricOutdated: options.rubricOutdated,
2223
2794
  });
2224
2795
  if (options.reference && options.randomReference) {
2225
2796
  throw new Error("--reference and --random-reference cannot be combined");
@@ -2239,6 +2810,7 @@ export function registerGradeCommand(program) {
2239
2810
  viewpoints,
2240
2811
  projectId,
2241
2812
  outputDirectory,
2813
+ embedDocuments: options.embedDocuments,
2242
2814
  doneCriteriaByPath: target === "deliverable"
2243
2815
  ? resolveDeliverableDoneCriteria(paths, options.project)
2244
2816
  : undefined,
@@ -2250,6 +2822,9 @@ export function registerGradeCommand(program) {
2250
2822
  if (options.randomReference && !plan.referenceExample) {
2251
2823
  process.stderr.write(`warning: no ready reference of the same kind for ${plan.target}; grading without a reference\n`);
2252
2824
  }
2825
+ if (options.embedDocuments && !plan.documentsEmbedded) {
2826
+ process.stderr.write(`warning: embedded documents for ${plan.target} would use ${plan.embeddingCharacterCount} characters and exceed the ${plan.embeddingCharacterLimit} character limit; falling back to path references\n`);
2827
+ }
2253
2828
  process.stdout.write(`${plan.changed ? "written" : "unchanged"}: ${plan.path}\n`);
2254
2829
  process.stdout.write(`${plan.reporterChanged ? "written" : "unchanged"}: ${plan.reporterPath}\n`);
2255
2830
  }
@@ -2261,10 +2836,11 @@ export function registerGradeCommand(program) {
2261
2836
  });
2262
2837
  addSelection(grade
2263
2838
  .command("apply")
2264
- .description("Validate reporter fidelity and JSON, calculate scores, and update documents"))
2265
- .requiredOption("--from <path>", "GradeSubmission JSON produced by the assessment agent")
2266
- .requiredOption("--by <nickname>", "Grading agent nickname from pm-members.yaml")
2267
- .option("--analysis-from <path>", "Executor analysis used to verify reporter fidelity (omit only for legacy one-stage output)")
2839
+ .description("Convert executor markers (or validate reporter JSON), calculate scores, and update documents"))
2840
+ .option("--from <path>", "GradeSubmission JSON produced by an LLM reporter; omit to convert --analysis-from mechanically")
2841
+ .requiredOption("--by <nickname>", "Grading agent nickname from agent-members.yaml")
2842
+ .option("--analysis-from <path>", "Executor analysis converted to GradeSubmission, or used to verify --from fidelity")
2843
+ .option("--submission-out <path>", "Write the GradeSubmission converted from --analysis-from to this repository path")
2268
2844
  .option("--reference <pathOrId>", "Comparison reference used during grading; recorded as a document id")
2269
2845
  .option("--dry-run", "Validate and list updates without writing", false)
2270
2846
  .action((options) => {
@@ -2273,37 +2849,89 @@ export function registerGradeCommand(program) {
2273
2849
  const viewpoints = loadViewpoints(options.project);
2274
2850
  const { project } = resolveProject(options.project);
2275
2851
  const gradedBy = resolveGradeActor(options.by, loadMemberRoster(specdojoRootDir(), project));
2276
- const submission = parseGradeSubmission(readFileSync(resolveSafeRepositoryPath(options.from, "--from"), "utf8"));
2852
+ if (!options.from && !options.analysisFrom) {
2853
+ throw new Error("grade apply requires --analysis-from, --from, or both");
2854
+ }
2855
+ if (options.submissionOut && (options.from || !options.analysisFrom)) {
2856
+ throw new Error("--submission-out requires --analysis-from without --from");
2857
+ }
2277
2858
  const selected = new Set(discoverGradeTargets({
2278
2859
  target,
2279
2860
  project: options.project,
2280
2861
  paths: options.path,
2281
2862
  changedOnly: options.changedOnly,
2863
+ dependencyChanged: options.dependencyChanged,
2864
+ rulebookChanged: options.rulebookChanged,
2865
+ unreviewed: options.unreviewed,
2282
2866
  verdict: options.verdict,
2283
2867
  minScore: options.minScore,
2284
2868
  maxFindings: options.maxFindings,
2285
2869
  ungraded: options.ungraded,
2286
2870
  incomplete: options.incomplete,
2871
+ rubricOutdated: options.rubricOutdated,
2287
2872
  }).map(repoRelativePath));
2288
2873
  const doneCriteriaByPath = target === "deliverable"
2289
2874
  ? resolveDeliverableDoneCriteria([...selected], options.project)
2290
2875
  : undefined;
2876
+ let submission;
2291
2877
  if (options.analysisFrom) {
2292
2878
  if (selected.size !== 1) {
2293
2879
  throw new Error("--analysis-from requires exactly one selected --path");
2294
2880
  }
2295
2881
  const expectedPath = [...selected][0];
2296
- const fidelityIssues = validateGradeReporterFidelity({
2297
- executorOutput: readFileSync(resolveSafeRepositoryPath(options.analysisFrom, "--analysis-from"), "utf8"),
2298
- submission,
2882
+ const executorOutput = readFileSync(resolveSafeRepositoryPath(options.analysisFrom, "--analysis-from"), "utf8");
2883
+ const conversionOptions = {
2884
+ executorOutput,
2299
2885
  viewpoints,
2300
2886
  target,
2301
2887
  expectedPath,
2302
2888
  doneCriteria: doneCriteriaByPath?.get(expectedPath),
2303
- });
2304
- if (fidelityIssues.length > 0) {
2305
- throw new Error(fidelityIssues.map((issue) => `${issue.path}: ${issue.message}`).join("\n"));
2889
+ };
2890
+ if (options.from) {
2891
+ // LLM reporter の JSON を executor marker と照合する互換・比較用の経路。
2892
+ submission = parseGradeSubmission(readFileSync(resolveSafeRepositoryPath(options.from, "--from"), "utf8"));
2893
+ const fidelityIssues = validateGradeReporterFidelity({
2894
+ ...conversionOptions,
2895
+ submission,
2896
+ });
2897
+ if (fidelityIssues.length > 0) {
2898
+ throw new Error(fidelityIssues.map((issue) => `${issue.path}: ${issue.message}`).join("\n"));
2899
+ }
2900
+ const converted = buildGradeSubmissionFromAnalysis(conversionOptions);
2901
+ if (converted.submission === undefined) {
2902
+ throw new Error(converted.issues.map((issue) => `${issue.path}: ${issue.message}`).join("\n"));
2903
+ }
2904
+ const convertedDocument = converted.submission.documents[0];
2905
+ const correctedLevels = new Map(convertedDocument.viewpoints.map((viewpoint) => [viewpoint.id, viewpoint.level]));
2906
+ submission.documents[0] = {
2907
+ ...submission.documents[0],
2908
+ viewpoints: submission.documents[0].viewpoints.map((viewpoint) => ({
2909
+ ...viewpoint,
2910
+ level: correctedLevels.get(viewpoint.id) ?? viewpoint.level,
2911
+ })),
2912
+ ...(convertedDocument.level_corrections
2913
+ ? { level_corrections: convertedDocument.level_corrections }
2914
+ : {}),
2915
+ };
2306
2916
  }
2917
+ else {
2918
+ const converted = buildGradeSubmissionFromAnalysis(conversionOptions);
2919
+ if (converted.submission === undefined) {
2920
+ throw new Error([
2921
+ "executor analysis rejected; rerun the executor",
2922
+ ...converted.issues.map((issue) => `${issue.path}: ${issue.message}`),
2923
+ ].join("\n"));
2924
+ }
2925
+ submission = converted.submission;
2926
+ if (options.submissionOut && !options.dryRun) {
2927
+ const submissionOut = resolveSafeRepositoryPath(options.submissionOut, "--submission-out");
2928
+ mkdirSync(dirname(submissionOut), { recursive: true });
2929
+ writeFileSync(submissionOut, `${JSON.stringify(submission, null, 2)}\n`, "utf8");
2930
+ }
2931
+ }
2932
+ }
2933
+ else {
2934
+ submission = parseGradeSubmission(readFileSync(resolveSafeRepositoryPath(options.from, "--from"), "utf8"));
2307
2935
  }
2308
2936
  for (const document of submission.documents)
2309
2937
  if (!selected.has(repoRelativePath(resolve(specdojoRootDir(), document.path))))
@@ -2318,6 +2946,7 @@ export function registerGradeCommand(program) {
2318
2946
  doneCriteriaByPath,
2319
2947
  criteriaDirectory: join(getProjectExecutionPath(project), "grade", "criteria"),
2320
2948
  resultsDirectory: join(getProjectExecutionPath(project), "grade", "results"),
2949
+ project: options.project,
2321
2950
  });
2322
2951
  for (const path of changed)
2323
2952
  process.stdout.write(`${options.dryRun ? "would update" : "updated"}: ${path}\n`);
@@ -2327,6 +2956,110 @@ export function registerGradeCommand(program) {
2327
2956
  commandError(error);
2328
2957
  }
2329
2958
  });
2959
+ addSelection(grade
2960
+ .command("translation-plan")
2961
+ .description("Create a Japanese translation request for the latest canonical findings"))
2962
+ .requiredOption("--out <path>", "Write the translation plan to this repository path")
2963
+ .option("--translation-index <index>", "Translate only this zero-based index from the translatable findings", requireNonNegativeInteger)
2964
+ .action((options) => {
2965
+ try {
2966
+ const target = requireTarget(options.target);
2967
+ const selected = discoverGradeTargets({
2968
+ target,
2969
+ project: options.project,
2970
+ paths: options.path,
2971
+ changedOnly: options.changedOnly,
2972
+ dependencyChanged: options.dependencyChanged,
2973
+ rulebookChanged: options.rulebookChanged,
2974
+ unreviewed: options.unreviewed,
2975
+ verdict: options.verdict,
2976
+ minScore: options.minScore,
2977
+ maxFindings: options.maxFindings,
2978
+ ungraded: options.ungraded,
2979
+ incomplete: options.incomplete,
2980
+ rubricOutdated: options.rubricOutdated,
2981
+ }).map(repoRelativePath);
2982
+ if (selected.length !== 1) {
2983
+ throw new Error("grade translation-plan requires exactly one selected --path");
2984
+ }
2985
+ const result = readGradeResultForDocument({
2986
+ documentPath: selected[0],
2987
+ project: options.project,
2988
+ });
2989
+ if (!result)
2990
+ throw new Error(`${selected[0]}: grade result not found`);
2991
+ if (result.target !== target) {
2992
+ throw new Error(`${selected[0]}: grade result target=${result.target}, expected=${target}`);
2993
+ }
2994
+ const output = resolveSafeRepositoryPath(options.out, "--out");
2995
+ mkdirSync(dirname(output), { recursive: true });
2996
+ const messages = gradeFindingTranslationInput(result, options.translationIndex);
2997
+ writeFileSync(output, renderGradeFindingTranslationPlan(result, options.translationIndex), "utf8");
2998
+ process.stdout.write(`written: ${repoRelativePath(output)}\nTranslations: ${messages.length}\n`);
2999
+ }
3000
+ catch (error) {
3001
+ commandError(error);
3002
+ }
3003
+ });
3004
+ addSelection(grade
3005
+ .command("localize")
3006
+ .description("Attach Japanese display messages to the latest canonical grade findings"))
3007
+ .requiredOption("--from <path>", "JSON string array returned by the translation agent")
3008
+ .option("--translation-index <index>", "Apply a retry for this zero-based index from the translatable findings", requireNonNegativeInteger)
3009
+ .requiredOption("--rejections-out <path>", "Write machine-readable rejected translation details as JSON")
3010
+ .action((options) => {
3011
+ try {
3012
+ const target = requireTarget(options.target);
3013
+ const selected = discoverGradeTargets({
3014
+ target,
3015
+ project: options.project,
3016
+ paths: options.path,
3017
+ changedOnly: options.changedOnly,
3018
+ dependencyChanged: options.dependencyChanged,
3019
+ rulebookChanged: options.rulebookChanged,
3020
+ unreviewed: options.unreviewed,
3021
+ verdict: options.verdict,
3022
+ minScore: options.minScore,
3023
+ maxFindings: options.maxFindings,
3024
+ ungraded: options.ungraded,
3025
+ incomplete: options.incomplete,
3026
+ rubricOutdated: options.rubricOutdated,
3027
+ }).map(repoRelativePath);
3028
+ if (selected.length !== 1) {
3029
+ throw new Error("grade localize requires exactly one selected --path");
3030
+ }
3031
+ const resultPath = gradeResultPathForDocument({
3032
+ documentPath: selected[0],
3033
+ project: options.project,
3034
+ });
3035
+ const result = readGradeResult(resultPath);
3036
+ if (!result)
3037
+ throw new Error(`${selected[0]}: grade result not found`);
3038
+ if (result.target !== target) {
3039
+ throw new Error(`${selected[0]}: grade result target=${result.target}, expected=${target}`);
3040
+ }
3041
+ let translations;
3042
+ try {
3043
+ translations = JSON.parse(extractJsonArrayText(readFileSync(resolveSafeRepositoryPath(options.from, "--from"), "utf8")));
3044
+ }
3045
+ catch (error) {
3046
+ translations = undefined;
3047
+ process.stderr.write(`warning: could not parse grade finding translations: ${error instanceof Error ? error.message : String(error)}\n`);
3048
+ }
3049
+ const localized = applyGradeFindingTranslations(result, translations, options.translationIndex);
3050
+ if (!localized.accepted) {
3051
+ process.stderr.write(`warning: rejected grade finding translations: ${localized.reason ?? "invalid output"}\n`);
3052
+ }
3053
+ const rejectionsPath = resolveSafeRepositoryPath(options.rejectionsOut, "--rejections-out");
3054
+ mkdirSync(dirname(rejectionsPath), { recursive: true });
3055
+ writeFileSync(rejectionsPath, `${JSON.stringify({ version: 1, rejections: localized.rejections }, null, 2)}\n`, "utf8");
3056
+ const changed = writeGradeResult(resultPath, localized.result);
3057
+ process.stdout.write(`${changed ? "updated" : "unchanged"}: ${repoRelativePath(resultPath)}\n`);
3058
+ }
3059
+ catch (error) {
3060
+ commandError(error);
3061
+ }
3062
+ });
2330
3063
  addSelection(grade.command("validate").description("Validate stored grade hashes and finding counts")).action((options) => {
2331
3064
  try {
2332
3065
  const target = requireTarget(options.target);
@@ -2335,11 +3068,15 @@ export function registerGradeCommand(program) {
2335
3068
  project: options.project,
2336
3069
  paths: options.path,
2337
3070
  changedOnly: options.changedOnly,
3071
+ dependencyChanged: options.dependencyChanged,
3072
+ rulebookChanged: options.rulebookChanged,
3073
+ unreviewed: options.unreviewed,
2338
3074
  verdict: options.verdict,
2339
3075
  minScore: options.minScore,
2340
3076
  maxFindings: options.maxFindings,
2341
3077
  ungraded: options.ungraded,
2342
3078
  incomplete: options.incomplete,
3079
+ rubricOutdated: options.rubricOutdated,
2343
3080
  });
2344
3081
  const errors = paths.flatMap((path) => validateGradeResultForDocument({ path, target, project: options.project }));
2345
3082
  for (const error of errors)