specdojo 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (245) hide show
  1. package/CHANGELOG.md +65 -0
  2. package/README.md +77 -18
  3. package/dist/catalog/build-references.js +144 -0
  4. package/dist/catalog/build-render.js +32 -0
  5. package/dist/{catalog-build.js → catalog/build.js} +18 -295
  6. package/dist/{catalog.js → catalog/catalog.js} +11 -11
  7. package/dist/{catalog-generate.js → catalog/generate.js} +13 -16
  8. package/dist/catalog/paths.js +1 -0
  9. package/dist/{catalog-plan-generate.js → catalog/plan-generate.js} +5 -5
  10. package/dist/{catalog-plan.js → catalog/plan.js} +9 -9
  11. package/dist/{catalog-scaffold.js → catalog/scaffold.js} +6 -6
  12. package/dist/{agent.js → commands/agent.js} +11 -11
  13. package/dist/{build-command.js → commands/build.js} +2 -2
  14. package/dist/{init-command.js → commands/init.js} +103 -37
  15. package/dist/{orchestrator.js → commands/orchestrator.js} +2 -2
  16. package/dist/{watch.js → commands/watch.js} +3 -3
  17. package/dist/dashboard/dashboard-timeline.js +175 -0
  18. package/dist/{dashboard.js → dashboard/dashboard.js} +16 -549
  19. package/dist/dashboard/exec-records.js +105 -0
  20. package/dist/dashboard/routines.js +256 -0
  21. package/dist/dashboard/shared.js +14 -0
  22. package/dist/{timeline-build.js → dashboard/timeline-build.js} +2 -1
  23. package/dist/{timeline.js → dashboard/timeline.js} +1 -1
  24. package/dist/{deliverable.js → deliverable/deliverable.js} +5 -5
  25. package/dist/{deliverable-trash.js → deliverable/trash.js} +7 -7
  26. package/dist/{devcontainer-command.js → devcontainer/command.js} +5 -3
  27. package/dist/{devcontainer-scaffold.js → devcontainer/scaffold.js} +94 -2
  28. package/dist/{doc-index.js → docs/doc-index.js} +3 -3
  29. package/dist/{frontmatter-namespace.js → docs/frontmatter-namespace.js} +2 -2
  30. package/dist/{index-command.js → docs/index-command.js} +1 -1
  31. package/dist/docs/template-resolution.js +1 -0
  32. package/dist/{viewpoint-document-kinds-check.js → docs/viewpoint-document-kinds-check.js} +3 -3
  33. package/dist/{yaml-pages-command.js → docs/yaml-pages-command.js} +1 -1
  34. package/dist/{yaml-pages.js → docs/yaml-pages.js} +5 -5
  35. package/dist/{exec-agent-config.js → exec/agent-config.js} +33 -4
  36. package/dist/{exec-agent-git-state.js → exec/agent-git-state.js} +1 -1
  37. package/dist/{exec-agent-protected-config.js → exec/agent-protected-config.js} +1 -1
  38. package/dist/{exec.js → exec/commands.js} +22 -467
  39. package/dist/exec/core.js +457 -0
  40. package/dist/{exec-events.js → exec/events.js} +2 -2
  41. package/dist/{exec-evidence.js → exec/evidence.js} +11 -6
  42. package/dist/exec/exec.js +2 -0
  43. package/dist/exec/format.js +1 -0
  44. package/dist/{exec-handoff.js → exec/handoff.js} +13 -12
  45. package/dist/{exec-limit.js → exec/limit.js} +93 -12
  46. package/dist/{exec-parent-validation.js → exec/parent-validation.js} +4 -4
  47. package/dist/{exec-pipeline-state.js → exec/pipeline-state.js} +16 -2
  48. package/dist/{exec-plans.js → exec/plans-core.js} +97 -468
  49. package/dist/exec/plans-generation.js +249 -0
  50. package/dist/exec/plans-storage.js +131 -0
  51. package/dist/exec/plans.js +3 -0
  52. package/dist/{exec-project.js → exec/project.js} +1 -1
  53. package/dist/{exec-protection-handoff.js → exec/protection-handoff.js} +3 -3
  54. package/dist/{exec-register-resume.js → exec/register-resume.js} +2 -2
  55. package/dist/{exec-register.js → exec/register.js} +92 -9
  56. package/dist/exec/repo-integration-git.js +23 -0
  57. package/dist/exec/repo-integration-sync.js +264 -0
  58. package/dist/{exec-repo-integration.js → exec/repo-integration.js} +13 -287
  59. package/dist/{exec-repo-trace.js → exec/repo-trace.js} +3 -3
  60. package/dist/exec/reporter-output.js +206 -0
  61. package/dist/{exec-reporter.js → exec/reporter.js} +29 -216
  62. package/dist/{exec-results.js → exec/results.js} +277 -36
  63. package/dist/exec/run/agent-pipeline.js +276 -0
  64. package/dist/exec/run/agent.js +583 -0
  65. package/dist/exec/run/in-place.js +570 -0
  66. package/dist/exec/run/job.js +746 -0
  67. package/dist/exec/run/lifecycle-commands.js +530 -0
  68. package/dist/{exec-run-lock.js → exec/run/lock.js} +4 -3
  69. package/dist/exec/run/mode-shared.js +140 -0
  70. package/dist/exec/run/register-command.js +252 -0
  71. package/dist/exec/run/register-core.js +411 -0
  72. package/dist/exec/run/register-mode.js +210 -0
  73. package/dist/exec/run/register-resume.js +398 -0
  74. package/dist/exec/run/register-state.js +325 -0
  75. package/dist/exec/run/register-worktree.js +540 -0
  76. package/dist/exec/run/run.js +11 -0
  77. package/dist/exec/run/schedule-mode.js +294 -0
  78. package/dist/exec/run/schedule-prepare.js +366 -0
  79. package/dist/exec/run/schedule-task.js +599 -0
  80. package/dist/exec/run/shared.js +449 -0
  81. package/dist/{exec-schedule-calendar.js → exec/schedule/calendar.js} +1 -1
  82. package/dist/{exec-schedule-cpm.js → exec/schedule/cpm.js} +2 -2
  83. package/dist/{exec-schedule-gantt-chart-render.js → exec/schedule/gantt-chart-render.js} +2 -2
  84. package/dist/exec/schedule/gantt-chart.js +2 -0
  85. package/dist/{exec-schedule-hash.js → exec/schedule/hash.js} +2 -2
  86. package/dist/exec/schedule/index.js +1 -0
  87. package/dist/{exec-schedule-initial.js → exec/schedule/initial.js} +2 -2
  88. package/dist/{exec-schedule-progress.js → exec/schedule/progress.js} +2 -2
  89. package/dist/{exec-schedule-ready.js → exec/schedule/ready.js} +2 -2
  90. package/dist/{exec-schedule.js → exec/schedule/schedule.js} +11 -11
  91. package/dist/exec/shared.js +63 -0
  92. package/dist/exec/slot-lock.js +1 -0
  93. package/dist/{exec-strategy.js → exec/strategy.js} +2 -2
  94. package/dist/{exec-task-repos.js → exec/task-repos.js} +2 -2
  95. package/dist/{exec-task-view.js → exec/task-view.js} +4 -4
  96. package/dist/{exec-trial.js → exec/trial-commands.js} +23 -388
  97. package/dist/exec/trial-core.js +371 -0
  98. package/dist/exec/trial.js +2 -0
  99. package/dist/{exec-worktree-command.js → exec/worktree-command.js} +25 -23
  100. package/dist/exec/worktree-ops-commit.js +672 -0
  101. package/dist/exec/worktree-ops-lifecycle.js +297 -0
  102. package/dist/exec/worktree-ops-merge.js +344 -0
  103. package/dist/exec/worktree-ops.js +3 -0
  104. package/dist/exec/worktree.js +305 -0
  105. package/dist/grade/apply.js +734 -0
  106. package/dist/grade/command-apply.js +250 -0
  107. package/dist/grade/command-inspect.js +138 -0
  108. package/dist/grade/command-plan.js +101 -0
  109. package/dist/grade/command-shared.js +68 -0
  110. package/dist/grade/core.js +307 -0
  111. package/dist/grade/grade.js +19 -0
  112. package/dist/grade/markdown.js +274 -0
  113. package/dist/grade/pipeline-state.js +184 -0
  114. package/dist/grade/plan.js +507 -0
  115. package/dist/{grade-result.js → grade/result.js} +7 -96
  116. package/dist/grade/target-discovery.js +265 -0
  117. package/dist/grade/targets.js +435 -0
  118. package/dist/{job.js → job/definition.js} +32 -574
  119. package/dist/job/job.js +568 -0
  120. package/dist/{kata-command.js → kata/command.js} +4 -4
  121. package/dist/{kata.js → kata/kata.js} +5 -5
  122. package/dist/register/approach.js +134 -0
  123. package/dist/register/command-types.js +1 -0
  124. package/dist/register/core.js +369 -0
  125. package/dist/register/create-commands.js +352 -0
  126. package/dist/{register-date.js → register/date.js} +1 -1
  127. package/dist/register/derivation.js +163 -0
  128. package/dist/{register-event-merge.js → register/event-merge.js} +32 -3
  129. package/dist/{register-events.js → register/events.js} +12 -6
  130. package/dist/{register-history.js → register/history.js} +7 -6
  131. package/dist/{register-item.js → register/item.js} +28 -10
  132. package/dist/register/lifecycle-lock.js +5 -0
  133. package/dist/register/maintenance-commands.js +193 -0
  134. package/dist/{register-migrate-timestamps.js → register/migrate-timestamps.js} +3 -3
  135. package/dist/register/migration.js +268 -0
  136. package/dist/register/register.js +404 -0
  137. package/dist/register/renumber.js +341 -0
  138. package/dist/register/transition-commands.js +248 -0
  139. package/dist/register/update.js +230 -0
  140. package/dist/register/views.js +296 -0
  141. package/dist/{review-grade.js → review/grade.js} +2 -2
  142. package/dist/{review-plan.js → review/plan.js} +5 -5
  143. package/dist/routine/definition.js +401 -0
  144. package/dist/{routine.js → routine/routine.js} +50 -419
  145. package/dist/{schedule-approach.js → schedule/approach.js} +9 -9
  146. package/dist/{schedule-build.js → schedule/build.js} +7 -4
  147. package/dist/{schedule.js → schedule/schedule.js} +9 -9
  148. package/dist/schedule/strategy-generate-document.js +273 -0
  149. package/dist/schedule/strategy-generate-scope.js +199 -0
  150. package/dist/schedule/strategy-generate.js +348 -0
  151. package/dist/shared/agent-types.js +23 -0
  152. package/dist/shared/artifact-path.js +9 -0
  153. package/dist/{build-if-stale.js → shared/build-if-stale.js} +1 -1
  154. package/dist/shared/catalog-render.js +115 -0
  155. package/dist/{exec-slot-lock.js → shared/cross-process-lock.js} +3 -1
  156. package/dist/shared/fs.js +30 -0
  157. package/dist/shared/git.js +316 -0
  158. package/dist/shared/grade-result.js +94 -0
  159. package/dist/{package-paths.js → shared/package-paths.js} +3 -3
  160. package/dist/shared/plan-templates.js +114 -0
  161. package/dist/{exec-provider-scaffold.js → shared/provider-scaffold.js} +3 -1
  162. package/dist/shared/random.js +4 -0
  163. package/dist/{exec-schedule-index.js → shared/schedule-index.js} +3 -1
  164. package/dist/shared/schedule-paths.js +9 -0
  165. package/dist/{specdojo-config.js → shared/specdojo-config.js} +96 -9
  166. package/dist/{exec-shared.js → shared/text.js} +0 -134
  167. package/dist/shared/time.js +28 -0
  168. package/dist/shared/yaml.js +28 -0
  169. package/dist/specdojo.js +22 -22
  170. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +29 -17
  171. package/docs/ja/specdojo/exec-templates/xep-register-investigate-template.md +1 -2
  172. package/docs/ja/specdojo/exec-templates/xep-register-template.md +1 -2
  173. package/docs/ja/specdojo/exec-templates/xer-template.md +1 -3
  174. package/docs/ja/specdojo/exec-templates/xrp-job-template.md +6 -4
  175. package/docs/ja/specdojo/guides/exec-config-guide.md +97 -22
  176. package/docs/ja/specdojo/guides/exec-operation-guide.md +145 -12
  177. package/docs/ja/specdojo/guides/exec-worktree-guide.md +2 -0
  178. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +51 -18
  179. package/docs/ja/specdojo/guides/quick-start-guide.md +81 -16
  180. package/docs/ja/specdojo/guides/register-operation-guide.md +2 -1
  181. package/docs/ja/specdojo/guides/remote-host-development-guide.md +10 -1
  182. package/docs/ja/specdojo/guides/review-guide.md +1 -1
  183. package/docs/ja/specdojo/guides/routine-operation-guide.md +6 -6
  184. package/docs/ja/specdojo/guides/use-case-guide.md +1 -1
  185. package/docs/ja/specdojo/references/command-reference.md +52 -28
  186. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +17 -11
  187. package/docs/ja/specdojo/standards/job-definition-standard.md +20 -18
  188. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +2 -2
  189. package/docs/ja/specdojo/templates/pjr-derived-items-template.md +22 -0
  190. package/docs/ja/specdojo/templates/pjr-index-template.md +1 -0
  191. package/docs/specdojo/schemas/v1/agent-members.schema.yaml +29 -2
  192. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +20 -0
  193. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +23 -0
  194. package/docs/specdojo/schemas/v1/job-run.schema.yaml +2 -2
  195. package/docs/specdojo/schemas/v1/job.schema.yaml +7 -0
  196. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +26 -0
  197. package/docs/specdojo/schemas/v1/register-events.schema.yaml +3 -0
  198. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +70 -7
  199. package/docs/specdojo/schemas/v1/routine-run.schema.yaml +1 -1
  200. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +1 -1
  201. package/package.json +4 -5
  202. package/templates/antigravity/README.md +7 -3
  203. package/templates/antigravity/agent-members-snippet.yaml +108 -12
  204. package/templates/antigravity/exec-defaults-snippet.yaml +10 -13
  205. package/templates/claude/README.md +27 -3
  206. package/templates/claude/agents/claude-executor.md +0 -1
  207. package/templates/claude/agents/claude-reporter.md +2 -1
  208. package/templates/claude/agents/claude-review-executor.md +0 -1
  209. package/templates/codex/README.md +23 -4
  210. package/templates/devcontainer/devcontainer.json +2 -2
  211. package/templates/devcontainer/remote-host/specdojo-tmux.sh.sample +69 -0
  212. package/templates/devcontainer/remote-host/ssh-config.sample +16 -0
  213. package/templates/init-agent-members.yaml +75 -25
  214. package/templates/init-exec-defaults.yaml +26 -8
  215. package/templates/opencode/README.md +17 -3
  216. package/templates/opencode/agents/opencode-executor.md +0 -1
  217. package/templates/opencode/agents/opencode-reporter.md +2 -1
  218. package/templates/opencode/agents/opencode-review-executor.md +0 -1
  219. package/dist/exec-run.js +0 -6182
  220. package/dist/exec-schedule-gantt-chart.js +0 -2
  221. package/dist/exec-worktree-ops.js +0 -1292
  222. package/dist/exec-worktree.js +0 -446
  223. package/dist/grade.js +0 -3193
  224. package/dist/register.js +0 -2407
  225. package/dist/schedule-strategy-generate.js +0 -812
  226. package/templates/claude/agents/claude-expert-review-executor.md +0 -14
  227. /package/dist/{catalog-plan-prompt.js → catalog/plan-prompt.js} +0 -0
  228. /package/dist/{catalog-types.js → catalog/types.js} +0 -0
  229. /package/dist/{template-frontmatter.js → docs/template-frontmatter.js} +0 -0
  230. /package/dist/{role-types.js → exec/role-types.js} +0 -0
  231. /package/dist/{exec-schedule-gantt-chart-scope.js → exec/schedule/gantt-chart-scope.js} +0 -0
  232. /package/dist/{exec-types.js → exec/types.js} +0 -0
  233. /package/dist/{review-types.js → review/types.js} +0 -0
  234. /package/dist/{schedule-phase-sets.js → schedule/phase-sets.js} +0 -0
  235. /package/dist/{schedule-strategy-profiles.js → schedule/strategy-profiles.js} +0 -0
  236. /package/dist/{agent-response.js → shared/agent-response.js} +0 -0
  237. /package/dist/{catalog-paths.js → shared/catalog-paths.js} +0 -0
  238. /package/dist/{dist-freshness.js → shared/dist-freshness.js} +0 -0
  239. /package/dist/{git-environment.js → shared/git-environment.js} +0 -0
  240. /package/dist/{exec-format.js → shared/markdown-format.js} +0 -0
  241. /package/dist/{practice-id.js → shared/practice-id.js} +0 -0
  242. /package/dist/{spawn-self.js → shared/spawn-self.js} +0 -0
  243. /package/dist/{specdojo-gitignore.js → shared/specdojo-gitignore.js} +0 -0
  244. /package/dist/{template-resolution.js → shared/template-resolution.js} +0 -0
  245. /package/dist/{yaml-schema-modeline.js → shared/yaml-schema-modeline.js} +0 -0
@@ -1,12 +1,15 @@
1
- import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
2
- import { join } from "node:path";
1
+ import { execFileSync } from "node:child_process";
2
+ import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
3
+ import { dirname, join, resolve, sep } from "node:path";
3
4
  import { isDeepStrictEqual } from "node:util";
4
- import { buildSpecdojoFrontmatter, parseSpecdojoDocument } from "./frontmatter-namespace.js";
5
- import { expandTemplate, stripTerminalControlSequences } from "./exec-shared.js";
6
- import { formatMarkdownFile } from "./exec-format.js";
7
- import { deriveReporterFacts, mechanicallyNotApplicableReason, runnerOwnedValidationReason, } from "./exec-reporter.js";
8
- import { resolveSpecdojoPath, resolveSpecdojoPathIfExists } from "./template-resolution.js";
9
- const MISSING_CHANGED_FILE_SUMMARY = "reporter の説明がないため、変更差分を参照。";
5
+ import { buildSpecdojoFrontmatter, parseSpecdojoDocument } from "../docs/frontmatter-namespace.js";
6
+ import { expandTemplate, stripTerminalControlSequences } from "./shared.js";
7
+ import { formatMarkdownFile } from "./format.js";
8
+ import { deriveReporterFacts, mechanicallyNotApplicableReason, runnerOwnedValidationReason, } from "./reporter.js";
9
+ import { resolveSpecdojoPath, resolveSpecdojoPathIfExists } from "../docs/template-resolution.js";
10
+ import { dump } from "../shared/yaml.js";
11
+ import { gitEnvironment } from "../shared/git-environment.js";
12
+ export const MAX_INDIVIDUAL_CHANGED_FILES = 50;
10
13
  // ---------------------------------------------------------------------------
11
14
  // Frontmatter helpers
12
15
  // ---------------------------------------------------------------------------
@@ -15,28 +18,35 @@ const MISSING_CHANGED_FILE_SUMMARY = "reporter の説明がないため、変更
15
18
  function parseOrigin(value) {
16
19
  return value === "register" || value === "schedule" || value === "job" ? value : undefined;
17
20
  }
21
+ // js-yaml に単一スカラーとして直列化させ、通常の識別子は従来どおり plain style のまま
22
+ // 保つ。改行を含む値だけは block scalar を frontmatter の行配列へ安全に埋め込めないため、
23
+ // YAML 1.2 でも有効な JSON の二重引用符形式へフォールバックする。
24
+ function serializeYamlString(value) {
25
+ const serialized = dump(value, { lineWidth: -1, noRefs: true }).replace(/\n$/, "");
26
+ return serialized.includes("\n") ? JSON.stringify(value) : serialized;
27
+ }
18
28
  function serializeFrontmatter(meta) {
19
29
  const inner = [
20
- `id: ${meta.id}`,
30
+ `id: ${serializeYamlString(meta.id)}`,
21
31
  `type: ${meta.type}`,
22
- `task_id: ${meta.task_id}`,
32
+ `task_id: ${serializeYamlString(meta.task_id)}`,
23
33
  `mode: ${meta.mode}`,
24
34
  `status: ${meta.status}`,
25
- `project_id: ${meta.project_id}`,
35
+ `project_id: ${serializeYamlString(meta.project_id)}`,
26
36
  ];
27
37
  if (meta.origin)
28
38
  inner.push(`origin: ${meta.origin}`);
29
39
  if (meta.job_id)
30
- inner.push(`job_id: ${meta.job_id}`);
40
+ inner.push(`job_id: ${serializeYamlString(meta.job_id)}`);
31
41
  if (meta.run_id)
32
- inner.push(`run_id: ${meta.run_id}`);
42
+ inner.push(`run_id: ${serializeYamlString(meta.run_id)}`);
33
43
  if (meta.plan_ref)
34
- inner.push(`plan_ref: ${meta.plan_ref}`);
35
- inner.push(`started_at: "${meta.started_at}"`);
44
+ inner.push(`plan_ref: ${serializeYamlString(meta.plan_ref)}`);
45
+ inner.push(`started_at: ${JSON.stringify(meta.started_at)}`);
36
46
  if (meta.completed_at)
37
- inner.push(`completed_at: "${meta.completed_at}"`);
47
+ inner.push(`completed_at: ${JSON.stringify(meta.completed_at)}`);
38
48
  if (meta.agent)
39
- inner.push(`agent: ${meta.agent}`);
49
+ inner.push(`agent: ${serializeYamlString(meta.agent)}`);
40
50
  if (meta.execution)
41
51
  inner.push(`execution: ${meta.execution}`);
42
52
  if (meta.approach)
@@ -44,15 +54,14 @@ function serializeFrontmatter(meta) {
44
54
  if (meta.targets && meta.targets.length > 0) {
45
55
  inner.push("targets:");
46
56
  for (const target of meta.targets)
47
- inner.push(` - ${target}`);
57
+ inner.push(` - ${serializeYamlString(target)}`);
48
58
  }
49
59
  // reason は agent stderr や subprocess の生出力由来で任意文字を含みうる。まず ANSI エスケープ
50
- // シーケンスや制御文字を除去し(色付き hook 出力が result 表示を壊すのを防ぐ)、YAML として
51
- // 安全にするため二重引用符内へ収め、内部の二重引用符は単引用符へ置換する(extractBlockReason は
52
- // 単一行を返すため改行は無い)。
60
+ // シーケンスや制御文字を除去し(色付き hook 出力が result 表示を壊すのを防ぐ)、JSON の
61
+ // 文字列形式で YAML へ埋め込む。改行・引用符・バックスラッシュも値を変えずに保持できる。
53
62
  if (meta.block_reason) {
54
- const safeReason = stripTerminalControlSequences(meta.block_reason).replace(/"/g, "'");
55
- inner.push(`block_reason: "${safeReason}"`);
63
+ const safeReason = stripTerminalControlSequences(meta.block_reason);
64
+ inner.push(`block_reason: ${JSON.stringify(safeReason)}`);
56
65
  }
57
66
  return buildSpecdojoFrontmatter(inner);
58
67
  }
@@ -148,6 +157,16 @@ async function supersedePriorResults(resultsDir, taskId, nextResultPath, superse
148
157
  }
149
158
  return supersededPaths;
150
159
  }
160
+ const APPROACH_SECTION_WITH_APPROACH = [
161
+ "## 4. 進め方と実践の型の適用",
162
+ "",
163
+ "_TODO_: `approach` に従ってどう進めたか、その進め方の中で実践の型(rulebook / recipe / sample / template)をどう適用したかを記入する(`fully-guided` で rulebook / recipe / sample / template をどう使い分けたか、`recipe-guided` で recipe のみを基準にした内容、`freeform` で実践の型より優先した実例やプロジェクト文脈、`retrofit` で実際に参照した実装パス・抽出した現在動作・反映/新設判断・未反映の乖離・未確認範囲、`rulebook-maintenance` などの maintenance 系で見直した実践の型とその根拠、など)。実践の型を基準にしなかった場合は、その判断と代わりに根拠にした内容も記入する。複数文書間に矛盾があり rulebook を正として判断した箇所、参照範囲から外れていた文書とその代わりに根拠にした内容があれば、あわせて記録する。",
164
+ ].join("\n");
165
+ const APPROACH_SECTION_WITHOUT_APPROACH = [
166
+ "## 4. 進め方",
167
+ "",
168
+ "_TODO_: どう進めたか、根拠にした文書や規約を記入する。",
169
+ ].join("\n");
151
170
  export async function scaffoldResult(opts) {
152
171
  const { executionPath, taskId, mode, projectId, planRef, agent, startedAt, approach } = opts;
153
172
  const stem = opts.stem ?? taskId;
@@ -177,7 +196,12 @@ export async function scaffoldResult(opts) {
177
196
  ...(approach ? { approach } : {}),
178
197
  ...(opts.targets && opts.targets.length > 0 ? { targets: opts.targets } : {}),
179
198
  };
180
- const values = { _FRONTMATTER_: serializeFrontmatter(meta) };
199
+ const values = {
200
+ _FRONTMATTER_: serializeFrontmatter(meta),
201
+ _APPROACH_SECTION_: approach
202
+ ? APPROACH_SECTION_WITH_APPROACH
203
+ : APPROACH_SECTION_WITHOUT_APPROACH,
204
+ };
181
205
  // Finalize results pre-expand the confirmation record (done_criteria checklist and
182
206
  // ready-promotion targets) so every finalize is verified against the same items.
183
207
  // When the caller cannot resolve them, leave _TODO_ markers for manual fill-in.
@@ -185,7 +209,10 @@ export async function scaffoldResult(opts) {
185
209
  values._DONE_CRITERIA_CHECKLIST_ = opts.finalizeSections?.doneCriteriaChecklist ?? "_TODO_";
186
210
  values._FINALIZE_TARGETS_CHECKLIST_ = opts.finalizeSections?.targetsChecklist ?? "_TODO_";
187
211
  }
188
- const content = expandTemplate(template, values);
212
+ let content = expandTemplate(template, values);
213
+ if (!approach && content.includes("## 4. 進め方と実践の型の適用")) {
214
+ content = content.replace(APPROACH_SECTION_WITH_APPROACH, APPROACH_SECTION_WITHOUT_APPROACH);
215
+ }
189
216
  writeFileSync(resultPath, content, "utf8");
190
217
  await formatMarkdownFile(resultPath);
191
218
  const supersededPaths = await supersedePriorResults(resultsDir, taskId, resultPath, startedAt);
@@ -303,8 +330,127 @@ function reporterBulletList(values, empty) {
303
330
  return `- ${empty}`;
304
331
  return values.map((value) => `- ${reporterInlineText(value)}`).join("\n");
305
332
  }
306
- function renderEditReporterBody(output, evidence) {
333
+ function findGitRoot(startDir) {
334
+ try {
335
+ let current = resolve(startDir);
336
+ while (true) {
337
+ if (existsSync(join(current, ".git"))) {
338
+ return current;
339
+ }
340
+ const parent = dirname(current);
341
+ if (parent === current)
342
+ return null;
343
+ current = parent;
344
+ }
345
+ }
346
+ catch {
347
+ return null;
348
+ }
349
+ }
350
+ function collectGitLineStats(worktreeDir, files) {
351
+ const stats = new Map();
352
+ try {
353
+ const raw = execFileSync("git", ["diff", "--numstat", "-z", "HEAD", "--"], {
354
+ cwd: worktreeDir,
355
+ env: gitEnvironment(),
356
+ encoding: "utf8",
357
+ stdio: ["ignore", "pipe", "ignore"],
358
+ });
359
+ const parts = raw.split("\0");
360
+ for (let i = 0; i < parts.length; i++) {
361
+ const part = parts[i];
362
+ if (!part)
363
+ continue;
364
+ const match = part.match(/^(\d+|-)\t(\d+|-)\t(.*)$/);
365
+ if (match) {
366
+ const adds = match[1] === "-" ? 0 : parseInt(match[1], 10);
367
+ const dels = match[2] === "-" ? 0 : parseInt(match[2], 10);
368
+ let p = match[3];
369
+ if (!p && i + 2 < parts.length) {
370
+ const oldPath = parts[++i];
371
+ const newPath = parts[++i];
372
+ p = newPath;
373
+ stats.set(newPath, { additions: adds, deletions: dels });
374
+ stats.set(`${oldPath} -> ${newPath}`, { additions: adds, deletions: dels });
375
+ continue;
376
+ }
377
+ stats.set(p, { additions: adds, deletions: dels });
378
+ }
379
+ }
380
+ }
381
+ catch {
382
+ // git diff failed or worktree is not a git repository
383
+ }
384
+ for (const file of files) {
385
+ const targetPath = file.path.includes(" -> ") ? file.path.split(" -> ")[1] : file.path;
386
+ if (!stats.has(targetPath) && !stats.has(file.path)) {
387
+ if (file.status === "??" || file.status.includes("A")) {
388
+ try {
389
+ const fullPath = join(worktreeDir, targetPath);
390
+ if (existsSync(fullPath)) {
391
+ const stat = statSync(fullPath);
392
+ if (stat.isFile()) {
393
+ const fileContent = readFileSync(fullPath, "utf8");
394
+ const lines = fileContent.length === 0 ? 0 : fileContent.split("\n").length;
395
+ const entry = { additions: lines, deletions: 0 };
396
+ stats.set(targetPath, entry);
397
+ if (file.path !== targetPath) {
398
+ stats.set(file.path, entry);
399
+ }
400
+ }
401
+ }
402
+ }
403
+ catch {
404
+ // ignore unreadable files
405
+ }
406
+ }
407
+ }
408
+ }
409
+ return stats;
410
+ }
411
+ function formatMissingSummary(file, stats) {
412
+ const isRename = file.status.includes("R") || file.path.includes(" -> ");
413
+ const isAdd = file.status === "??" || file.status.includes("A");
414
+ const isDelete = file.status.includes("D");
415
+ let action;
416
+ if (isRename) {
417
+ const oldPath = file.path.includes(" -> ") ? file.path.split(" -> ")[0] : undefined;
418
+ action = oldPath ? `名前の変更(${reporterInlineText(oldPath)} から)` : "名前の変更";
419
+ }
420
+ else if (isAdd) {
421
+ action = "追加";
422
+ }
423
+ else if (isDelete) {
424
+ action = "削除";
425
+ }
426
+ else {
427
+ action = "変更";
428
+ }
429
+ if (stats !== undefined) {
430
+ return `${action}、+${stats.additions} / -${stats.deletions} 行`;
431
+ }
432
+ return action;
433
+ }
434
+ function getFileDirectory(filePath) {
435
+ let cleanPath = filePath;
436
+ let repoPrefix = "";
437
+ if (filePath.includes(":")) {
438
+ const colonIdx = filePath.indexOf(":");
439
+ repoPrefix = filePath.slice(0, colonIdx + 1);
440
+ cleanPath = filePath.slice(colonIdx + 1);
441
+ }
442
+ const dir = dirname(cleanPath).split(sep).join("/");
443
+ if (dir === "." || dir === "") {
444
+ return repoPrefix ? `${repoPrefix}./` : "./";
445
+ }
446
+ return repoPrefix ? `${repoPrefix}${dir}/` : `${dir}/`;
447
+ }
448
+ export function renderEditReporterBody(output, evidence, options) {
307
449
  const facts = deriveReporterFacts(evidence);
450
+ const lineStats = options?.lineStats ??
451
+ (options?.worktreeDir
452
+ ? collectGitLineStats(options.worktreeDir, facts.changed_files)
453
+ : undefined);
308
454
  const summariesByPath = new Map();
309
455
  for (const file of output.changed_files) {
310
456
  // The evidence path list remains authoritative. Ignore invented paths and keep the first
@@ -312,11 +458,90 @@ function renderEditReporterBody(output, evidence) {
312
458
  if (!summariesByPath.has(file.path))
313
459
  summariesByPath.set(file.path, file.summary);
314
460
  }
315
- const changedFiles = facts.changed_files.length === 0
316
- ? "- なし"
317
- : facts.changed_files
318
- .map((file) => `- \`${reporterInlineText(file.path).replace(/`/g, "'")}\`: ${reporterInlineText(summariesByPath.get(file.path) ?? MISSING_CHANGED_FILE_SUMMARY)}`)
461
+ const maxIndividual = options?.maxIndividualChangedFiles ?? MAX_INDIVIDUAL_CHANGED_FILES;
462
+ let changedFiles;
463
+ if (facts.changed_files.length === 0) {
464
+ changedFiles = "- なし";
465
+ }
466
+ else if (facts.changed_files.length <= maxIndividual) {
467
+ changedFiles = facts.changed_files
468
+ .map((file) => {
469
+ const displayPath = file.path.includes(" -> ") ? file.path.split(" -> ")[1] : file.path;
470
+ const reporterSummary = summariesByPath.get(displayPath) ?? summariesByPath.get(file.path);
471
+ const summary = reporterSummary !== undefined && reporterSummary.trim().length > 0
472
+ ? reporterSummary
473
+ : formatMissingSummary(file, lineStats?.get(displayPath) ?? lineStats?.get(file.path));
474
+ return `- \`${reporterInlineText(displayPath).replace(/`/g, "'")}\`: ${reporterInlineText(summary)}`;
475
+ })
319
476
  .join("\n");
477
+ }
478
+ else {
479
+ // Over threshold: list described files individually, and group undescribed files by directory.
480
+ const describedFiles = [];
481
+ const undescribedFiles = [];
482
+ const describedCountByDir = new Map();
483
+ for (const file of facts.changed_files) {
484
+ const displayPath = file.path.includes(" -> ") ? file.path.split(" -> ")[1] : file.path;
485
+ const reporterSummary = summariesByPath.get(displayPath) ?? summariesByPath.get(file.path);
486
+ if (reporterSummary !== undefined && reporterSummary.trim().length > 0) {
487
+ describedFiles.push({ displayPath, summary: reporterSummary });
488
+ const dir = getFileDirectory(displayPath);
489
+ describedCountByDir.set(dir, (describedCountByDir.get(dir) ?? 0) + 1);
490
+ }
491
+ else {
492
+ undescribedFiles.push({ displayPath, file });
493
+ }
494
+ }
495
+ const lines = [];
496
+ for (const entry of describedFiles) {
497
+ lines.push(`- \`${reporterInlineText(entry.displayPath).replace(/`/g, "'")}\`: ${reporterInlineText(entry.summary)}`);
498
+ }
499
+ const dirGroups = new Map();
500
+ for (const entry of undescribedFiles) {
501
+ const dir = getFileDirectory(entry.displayPath);
502
+ let group = dirGroups.get(dir);
503
+ if (!group) {
504
+ group = {
505
+ count: 0,
506
+ operations: new Map(),
507
+ additions: 0,
508
+ deletions: 0,
509
+ hasLineStats: false,
510
+ };
511
+ dirGroups.set(dir, group);
512
+ }
513
+ group.count++;
514
+ const isRename = entry.file.status.includes("R") || entry.file.path.includes(" -> ");
515
+ const isAdd = entry.file.status === "??" || entry.file.status.includes("A");
516
+ const isDelete = entry.file.status.includes("D");
517
+ const op = isRename ? "名前の変更" : isAdd ? "追加" : isDelete ? "削除" : "変更";
518
+ group.operations.set(op, (group.operations.get(op) ?? 0) + 1);
519
+ const stats = lineStats?.get(entry.displayPath) ?? lineStats?.get(entry.file.path);
520
+ if (stats !== undefined) {
521
+ group.additions += stats.additions;
522
+ group.deletions += stats.deletions;
523
+ group.hasLineStats = true;
524
+ }
525
+ }
526
+ const sortedDirs = [...dirGroups.keys()].sort((a, b) => a.localeCompare(b));
527
+ const operationOrder = ["変更", "追加", "削除", "名前の変更"];
528
+ for (const dir of sortedDirs) {
529
+ const group = dirGroups.get(dir);
530
+ const describedInDir = describedCountByDir.get(dir) ?? 0;
531
+ const countText = describedInDir > 0 ? `ほか ${group.count} 件` : `${group.count} 件`;
532
+ const sortedOps = [...group.operations.keys()].sort((a, b) => {
533
+ const idxA = operationOrder.indexOf(a);
534
+ const idxB = operationOrder.indexOf(b);
535
+ return (idxA === -1 ? 999 : idxA) - (idxB === -1 ? 999 : idxB);
536
+ });
537
+ const opParts = sortedOps.map((op) => `${op} ${group.operations.get(op)} 件`);
538
+ const lineStatsPart = group.hasLineStats
539
+ ? `、+${group.additions} / -${group.deletions} 行`
540
+ : "";
541
+ lines.push(`- \`${reporterInlineText(dir)}\`: ${countText}(${opParts.join("、")}${lineStatsPart})`);
542
+ }
543
+ changedFiles = lines.length === 0 ? "- なし" : lines.join("\n");
544
+ }
320
545
  const unchangedTargetNotes = (evidence?.target_coverage ?? [])
321
546
  .filter((entry) => entry.status === "unchanged")
322
547
  .map((entry) => {
@@ -356,6 +581,9 @@ function renderEditReporterBody(output, evidence) {
356
581
  const command = reporterInlineText(validation.command).replace(/`/g, "'");
357
582
  return [`適用外の検証(runner の判定): \`${command}\`(${reporterInlineText(reason)})`];
358
583
  });
584
+ const rateLimitRecoveryNotes = (evidence.rate_limit_events ?? []).map((event) => event.action === "wait"
585
+ ? `rate limit 後に ${event.resume_at ?? "再開可能時刻"} まで待ち、${event.to_actor} で ${event.resumed_at} に再開`
586
+ : `rate limit 後に ${event.from_actor} から ${event.to_actor} へ切り替え、${event.resumed_at} に再開`);
359
587
  return [
360
588
  "# Edit Result",
361
589
  "",
@@ -376,16 +604,20 @@ function renderEditReporterBody(output, evidence) {
376
604
  ...runnerOwnedValidationNotes,
377
605
  ...runnerJudgedNotApplicableNotes,
378
606
  ...humanValidationNotes,
607
+ ...rateLimitRecoveryNotes,
379
608
  ], "なし"),
380
609
  "",
381
- "## 4. 進め方と実践の型の適用",
610
+ options?.approach ? "## 4. 進め方と実践の型の適用" : "## 4. 進め方",
382
611
  "",
383
612
  reporterInlineText(output.approach),
384
613
  ].join("\n");
385
614
  }
386
615
  // review result の章立ては xrr-template.md と一致させる。review は成果物を再評価しないため、
387
616
  // 観点別の結果ではなく評価結果の確認・判断根拠・改善指示・verdict を記録する。
388
- function renderReviewReporterBody(output) {
617
+ function renderReviewReporterBody(output, evidence) {
618
+ const rateLimitRecoveryNotes = (evidence.rate_limit_events ?? []).map((event) => event.action === "wait"
619
+ ? `rate limit 後に ${event.resume_at ?? "再開可能時刻"} まで待ち、${event.to_actor} で ${event.resumed_at} に再開`
620
+ : `rate limit 後に ${event.from_actor} から ${event.to_actor} へ切り替え、${event.resumed_at} に再開`);
389
621
  return [
390
622
  "# Review Result",
391
623
  "",
@@ -395,7 +627,7 @@ function renderReviewReporterBody(output) {
395
627
  "",
396
628
  "## 2. 判断根拠",
397
629
  "",
398
- reporterBulletList(output.rationale, "なし"),
630
+ reporterBulletList([...output.rationale, ...rateLimitRecoveryNotes], "なし"),
399
631
  "",
400
632
  "## 3. 未充足事項・改善指示",
401
633
  "",
@@ -414,7 +646,7 @@ function renderReviewReporterBody(output) {
414
646
  * Replaces only the result body from schema-validated reporter data. The scaffolded frontmatter
415
647
  * remains byte-for-byte runner-owned until the lifecycle status update serializes it.
416
648
  */
417
- export async function renderReporterResult(resultPath, output, evidence) {
649
+ export async function renderReporterResult(resultPath, output, evidence, options) {
418
650
  if (!existsSync(resultPath))
419
651
  throw new Error(`Result not found: ${resultPath}`);
420
652
  const content = readFileSync(resultPath, "utf8");
@@ -425,9 +657,18 @@ export async function renderReporterResult(resultPath, output, evidence) {
425
657
  const frontmatter = content.match(/^---\r?\n[\s\S]*?\r?\n---/)?.[0];
426
658
  if (!frontmatter)
427
659
  throw new Error(`Result frontmatter not found: ${resultPath}`);
660
+ const approach = options?.approach ??
661
+ (typeof parsed.data.approach === "string" && parsed.data.approach.trim().length > 0
662
+ ? parsed.data.approach
663
+ : undefined);
664
+ const resolvedOptions = {
665
+ ...options,
666
+ ...(approach ? { approach } : {}),
667
+ worktreeDir: options?.worktreeDir ?? findGitRoot(dirname(resultPath)) ?? undefined,
668
+ };
428
669
  const body = output.mode === "edit"
429
- ? renderEditReporterBody(output, evidence)
430
- : renderReviewReporterBody(output);
670
+ ? renderEditReporterBody(output, evidence, resolvedOptions)
671
+ : renderReviewReporterBody(output, evidence);
431
672
  writeFileSync(resultPath, frontmatterWithBody(frontmatter, body), "utf8");
432
673
  await formatMarkdownFile(resultPath);
433
674
  }