specdojo 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (104) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/dist/catalog-build-references.js +144 -0
  3. package/dist/catalog-build-render.js +144 -0
  4. package/dist/catalog-build.js +13 -290
  5. package/dist/catalog-generate.js +6 -9
  6. package/dist/catalog-plan-generate.js +2 -2
  7. package/dist/catalog-plan.js +6 -6
  8. package/dist/catalog-scaffold.js +4 -4
  9. package/dist/catalog.js +2 -2
  10. package/dist/dashboard-exec-records.js +105 -0
  11. package/dist/dashboard-routines.js +255 -0
  12. package/dist/dashboard-shared.js +14 -0
  13. package/dist/dashboard-timeline.js +175 -0
  14. package/dist/dashboard.js +10 -544
  15. package/dist/deliverable-trash.js +3 -3
  16. package/dist/doc-index.js +3 -3
  17. package/dist/exec-commands.js +557 -0
  18. package/dist/exec-core.js +457 -0
  19. package/dist/exec-plans-core.js +693 -0
  20. package/dist/exec-plans-generation.js +206 -0
  21. package/dist/exec-plans-storage.js +131 -0
  22. package/dist/exec-plans.js +3 -1018
  23. package/dist/exec-repo-integration-git.js +23 -0
  24. package/dist/exec-repo-integration-sync.js +264 -0
  25. package/dist/exec-repo-integration.js +4 -281
  26. package/dist/exec-reporter-output.js +206 -0
  27. package/dist/exec-reporter.js +2 -206
  28. package/dist/exec-results.js +22 -15
  29. package/dist/exec-run-agent-pipeline.js +256 -0
  30. package/dist/exec-run-agent.js +531 -0
  31. package/dist/exec-run-in-place.js +541 -0
  32. package/dist/exec-run-job.js +717 -0
  33. package/dist/exec-run-lifecycle-commands.js +522 -0
  34. package/dist/exec-run-mode-shared.js +140 -0
  35. package/dist/exec-run-register-command.js +244 -0
  36. package/dist/exec-run-register-core.js +386 -0
  37. package/dist/exec-run-register-mode.js +206 -0
  38. package/dist/exec-run-register-resume.js +393 -0
  39. package/dist/exec-run-register-state.js +322 -0
  40. package/dist/exec-run-register-worktree.js +509 -0
  41. package/dist/exec-run-schedule-mode.js +294 -0
  42. package/dist/exec-run-schedule-prepare.js +353 -0
  43. package/dist/exec-run-schedule-task.js +572 -0
  44. package/dist/exec-run-shared.js +399 -0
  45. package/dist/exec-run.js +11 -6182
  46. package/dist/exec-shared.js +2 -2
  47. package/dist/exec-trial-commands.js +558 -0
  48. package/dist/exec-trial-core.js +371 -0
  49. package/dist/exec-trial.js +2 -921
  50. package/dist/exec-worktree-ops-commit.js +707 -0
  51. package/dist/exec-worktree-ops-lifecycle.js +292 -0
  52. package/dist/exec-worktree-ops-merge.js +303 -0
  53. package/dist/exec-worktree-ops.js +3 -1292
  54. package/dist/exec-worktree.js +32 -4
  55. package/dist/exec.js +2 -1006
  56. package/dist/frontmatter-namespace.js +2 -2
  57. package/dist/grade-apply.js +734 -0
  58. package/dist/grade-command-apply.js +250 -0
  59. package/dist/grade-command-inspect.js +138 -0
  60. package/dist/grade-command-plan.js +101 -0
  61. package/dist/grade-command-shared.js +68 -0
  62. package/dist/grade-core.js +307 -0
  63. package/dist/grade-markdown.js +274 -0
  64. package/dist/grade-pipeline-state.js +184 -0
  65. package/dist/grade-plan.js +507 -0
  66. package/dist/grade-result.js +5 -5
  67. package/dist/grade-target-discovery.js +265 -0
  68. package/dist/grade-targets.js +432 -0
  69. package/dist/grade.js +14 -3188
  70. package/dist/init-command.js +7 -7
  71. package/dist/job-definition.js +670 -0
  72. package/dist/job.js +9 -673
  73. package/dist/kata-command.js +2 -2
  74. package/dist/register-command-types.js +1 -0
  75. package/dist/register-core.js +363 -0
  76. package/dist/register-create-commands.js +245 -0
  77. package/dist/register-events.js +4 -4
  78. package/dist/register-item.js +6 -6
  79. package/dist/register-maintenance-commands.js +187 -0
  80. package/dist/register-migration.js +268 -0
  81. package/dist/register-renumber.js +314 -0
  82. package/dist/register-transition-commands.js +248 -0
  83. package/dist/register-update.js +230 -0
  84. package/dist/register-views.js +256 -0
  85. package/dist/register.js +61 -2069
  86. package/dist/review-plan.js +3 -3
  87. package/dist/routine-definition.js +401 -0
  88. package/dist/routine.js +6 -402
  89. package/dist/schedule-approach.js +2 -2
  90. package/dist/schedule-strategy-generate-document.js +273 -0
  91. package/dist/schedule-strategy-generate-scope.js +199 -0
  92. package/dist/schedule-strategy-generate.js +9 -473
  93. package/dist/schedule.js +4 -4
  94. package/dist/specdojo-config.js +3 -4
  95. package/dist/viewpoint-document-kinds-check.js +3 -3
  96. package/dist/yaml-pages.js +4 -4
  97. package/dist/yaml.js +28 -0
  98. package/docs/ja/specdojo/guides/exec-config-guide.md +6 -6
  99. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +20 -18
  100. package/docs/ja/specdojo/guides/routine-operation-guide.md +1 -1
  101. package/package.json +4 -5
  102. package/templates/antigravity/README.md +3 -3
  103. package/templates/antigravity/exec-defaults-snippet.yaml +6 -4
  104. package/templates/init-exec-defaults.yaml +3 -1
@@ -0,0 +1,206 @@
1
+ import { join } from "node:path";
2
+ import { loadExecDefaultsConfig, ProviderConcurrencyGate } from "./exec-agent-config.js";
3
+ import { activateResolvedProjectPaths, resolveProjectPaths } from "./exec-project.js";
4
+ import { qualifyTaskId } from "./exec-shared.js";
5
+ import { specdojoRootDir } from "./specdojo-config.js";
6
+ import { execLifecyclePoolPath, execLocksDir } from "./exec-run-lock.js";
7
+ import { CrossProcessMutex } from "./exec-slot-lock.js";
8
+ import { buildInPlaceStem } from "./exec-plans.js";
9
+ import { formatRegisterRunSummary, parseRegisterIds, parseRegisterSelectionFilter, registerRunExitCode, requireRunnableRegisterItem, resolveRegisterRunTarget, selectRegisterItems, } from "./exec-register.js";
10
+ import { loadRegisterItems, resolveRegisterPaths } from "./register.js";
11
+ import { findExecWorktree, resolveWorktreeBase } from "./exec-worktree.js";
12
+ import { findResumableRegisterRun } from "./exec-register-resume.js";
13
+ import { configuredWorktreeBase, parseParallel, resolveExecDefaultsPath, runCompletionDrivenWorkerPool, } from "./exec-run-shared.js";
14
+ import { loadRosterForExecutionPath } from "./exec-run-agent.js";
15
+ import { resolveRegisterCommand, isRegisterPipelineRequested, parseRegisterExecutorSelection, selectedRegisterExecutor, resolveRegisterPipelineCommand, runSingleRegisterItem, } from "./exec-run-register-core.js";
16
+ import { runSingleRegisterItemWorktree } from "./exec-run-register-worktree.js";
17
+ import { resumeSingleRegisterItemWorktree } from "./exec-run-register-resume.js";
18
+ // register 項目の実行(複数ID)。in-place モードは指定順に1件ずつ直列実行し、各IDが plan/result
19
+ // 生成・start・agent実行・review/waiting 遷移まで完結してから次へ進む。worktree モードは成果物を
20
+ // worktree に隔離し、状態遷移を root で直列化する(--parallel で並列化可能)。失敗時は
21
+ // failureMode(stop: 残りを skip / continue: 継続)に従う。最後にID別の成否・状態遷移・
22
+ // commit結果を一覧表示し、いずれかが failure ならプロセス終了コードへ反映する。
23
+ export async function runRegisterMode(opts) {
24
+ const resolvedPaths = resolveProjectPaths({ project: opts.project });
25
+ activateResolvedProjectPaths(resolvedPaths);
26
+ const { schedulePath, executionPath } = resolvedPaths;
27
+ const repoRoot = specdojoRootDir();
28
+ const projectId = resolvedPaths.projectId ?? opts.project ?? process.env.SPECDOJO_PROJECT ?? "";
29
+ if (!projectId) {
30
+ throw new Error("--register requires a project id. Use --project <id> or set current_project in specdojo.config.json.");
31
+ }
32
+ const selectionFilter = opts.registerFilter
33
+ ? parseRegisterSelectionFilter({
34
+ types: opts.registerTypes,
35
+ priorities: opts.registerPriorities,
36
+ statuses: opts.registerStatuses,
37
+ limit: opts.registerLimit,
38
+ })
39
+ : undefined;
40
+ const selectedIds = selectionFilter
41
+ ? selectRegisterItems(loadRegisterItems(resolveRegisterPaths({ project: projectId })).map((view) => view.item), selectionFilter).map((item) => item.id)
42
+ : undefined;
43
+ const { ids, duplicates } = selectedIds
44
+ ? { ids: selectedIds, duplicates: [] }
45
+ : parseRegisterIds(opts.register);
46
+ const executorSelection = parseRegisterExecutorSelection(opts.executorBy, ids);
47
+ if (ids.length === 0) {
48
+ process.stdout.write("No matching register items.\n");
49
+ return;
50
+ }
51
+ const hasExecutorSelection = executorSelection.kind !== "none";
52
+ const optsForItem = (pjrId) => ({
53
+ ...opts,
54
+ executorBy: selectedRegisterExecutor(executorSelection, pjrId),
55
+ });
56
+ for (const duplicate of duplicates) {
57
+ process.stdout.write(`Skipping duplicate register item id: ${duplicate}\n`);
58
+ }
59
+ const failureMode = opts.onFailure
60
+ ? opts.onFailure
61
+ : "stop";
62
+ // --executor-by / --reporter-by は両方揃って初めて pipeline モードになる。片方だけの指定は
63
+ // 曖昧なため、実行前に明示的なエラーで止める(isRegisterPipelineRequested は片方でも true を
64
+ // 返すため、resolveRegisterPipelineCommand 側の対称チェックとは別に、ここで早期に検知する)。
65
+ // 再開は state が示す段だけを実行する。stale executor の再実行では各 agent の明示指定を
66
+ // 個別に許可し、省略時は state に記録された actor を使う。
67
+ if (!opts.resume &&
68
+ ((hasExecutorSelection && !opts.reporterBy) || (!hasExecutorSelection && opts.reporterBy))) {
69
+ throw new Error("--register pipeline execution requires both --executor-by and --reporter-by.");
70
+ }
71
+ const roster = loadRosterForExecutionPath(executionPath);
72
+ const execDefaults = loadExecDefaultsConfig(resolveExecDefaultsPath(opts, schedulePath), executionPath);
73
+ const useWorktree = !!opts.worktree;
74
+ const parallel = parseParallel(opts.parallel);
75
+ const worktreeBase = resolveWorktreeBase(repoRoot, opts.worktreeBase, configuredWorktreeBase(schedulePath));
76
+ if (opts.dryRun && opts.resume) {
77
+ process.stdout.write(`[dry-run] resume pipeline for register items: ${ids.join(", ")}\n`);
78
+ for (const pjrId of ids) {
79
+ const { item } = resolveRegisterRunTarget(projectId, pjrId);
80
+ requireRunnableRegisterItem(item);
81
+ const worktree = findExecWorktree(repoRoot, qualifyTaskId(projectId, item.id));
82
+ if (!worktree) {
83
+ process.stdout.write(`[dry-run] ${item.id}: no exec worktree — not resumable\n`);
84
+ continue;
85
+ }
86
+ const lookup = findResumableRegisterRun({
87
+ repoRoot,
88
+ worktreePath: worktree.path,
89
+ executionPath,
90
+ taskId: item.id,
91
+ ...(opts.resumeFrom === "executor" ? { resumeFrom: "executor" } : {}),
92
+ });
93
+ process.stdout.write(lookup.kind === "resumable"
94
+ ? `[dry-run] ${item.id}: resume the ${lookup.target.stage} stage of run ${lookup.target.runId} in ${worktree.path}\n`
95
+ : `[dry-run] ${item.id}: not resumable (${lookup.reason})\n`);
96
+ }
97
+ return;
98
+ }
99
+ if (opts.dryRun) {
100
+ const modeLabel = useWorktree
101
+ ? `worktree${parallel > 1 ? `, parallel: ${parallel}` : ", serial"}`
102
+ : "in-place, serial";
103
+ process.stdout.write(`[dry-run] register items (${modeLabel}): ${ids.join(", ")} [on-failure: ${failureMode}, commit: ${useWorktree ? "always (worktree)" : opts.registerCommit ? "per-id" : "off"}]\n`);
104
+ const pipelineMode = isRegisterPipelineRequested(opts);
105
+ for (const pjrId of ids) {
106
+ const itemOpts = optsForItem(pjrId);
107
+ const { item } = resolveRegisterRunTarget(projectId, pjrId);
108
+ const category = requireRunnableRegisterItem(item);
109
+ const stem = buildInPlaceStem(pjrId.toLowerCase());
110
+ process.stdout.write(`[dry-run] register item: ${item.id} — ${item.title} [${item.type}/${category}]\n`);
111
+ if (pipelineMode) {
112
+ const { executor, reporterCandidates } = resolveRegisterPipelineCommand(roster, itemOpts, execDefaults);
113
+ process.stdout.write(`[dry-run] executor: ${executor.actor}\n`);
114
+ process.stdout.write(`[dry-run] executor command: ${executor.command}\n`);
115
+ process.stdout.write(`[dry-run] reporter: ${reporterCandidates[0]?.actor}\n`);
116
+ process.stdout.write(`[dry-run] reporter command: ${reporterCandidates[0]?.command}\n`);
117
+ }
118
+ else {
119
+ const { command, actor } = resolveRegisterCommand(item, roster, itemOpts, execDefaults);
120
+ process.stdout.write(`[dry-run] actor: ${actor}\n`);
121
+ process.stdout.write(`[dry-run] command: ${command}\n`);
122
+ }
123
+ process.stdout.write(`[dry-run] plan: ${join(executionPath, "exec", "plans", `${stem}-plan.md`)}\n`);
124
+ }
125
+ process.stdout.write(`[dry-run] cwd: ${useWorktree ? `${worktreeBase}/<worktree>` : repoRoot}\n`);
126
+ process.stdout.write(`[dry-run] transitions: start (in-progress) → review on success / waiting on failure\n`);
127
+ return;
128
+ }
129
+ const context = {
130
+ projectId,
131
+ schedulePath,
132
+ executionPath,
133
+ repoRoot,
134
+ roster,
135
+ execDefaults,
136
+ // provider の max_concurrency は、同じ project の exec run(主 run と --join run)を跨いで
137
+ // ロックディレクトリの枠で統制する。
138
+ providerConcurrencyGate: new ProviderConcurrencyGate(execDefaults, execLocksDir(executionPath)),
139
+ registerCommit: !!opts.registerCommit,
140
+ worktree: useWorktree,
141
+ worktreeBase,
142
+ };
143
+ const skippedSummary = (pjrId) => ({
144
+ id: pjrId,
145
+ title: "-",
146
+ outcome: "skipped",
147
+ transition: "none",
148
+ commit: "skipped",
149
+ reason: "stopped after an earlier failure (--on-failure stop)",
150
+ });
151
+ const summaries = [];
152
+ // 再開は既存 worktree の reporter 段だけを実行する。それ以外の経路(plan 生成・executor 実行)
153
+ // は通らないため、通常実行と同じ並列・直列の枠だけを共有する。
154
+ const runItem = (pjrId, lifecycleLock) => opts.resume
155
+ ? resumeSingleRegisterItemWorktree(context, optsForItem(pjrId), pjrId, lifecycleLock)
156
+ : runSingleRegisterItemWorktree(context, optsForItem(pjrId), pjrId, lifecycleLock);
157
+ // worktree 実行の root 側の手順(start 遷移・checkpoint・merge・wait commit・派生ビューの
158
+ // 再生成)は、同じ project の別プロセス(--join run)とも重ならないよう、ロックディレクトリの
159
+ // mutex で直列化する。一方の run が root に記帳ファイルを書いている途中で、もう一方の統合が
160
+ // 始まらない。直列実行でも別プロセスと重なり得るため、並列・直列の両方で使う。
161
+ const lifecycleLock = useWorktree
162
+ ? new CrossProcessMutex(execLifecyclePoolPath(executionPath), { actor: opts.by ?? "exec-run", label: ids.join(",") }, {
163
+ onWait: () => process.stdout.write(" Waiting for the register lifecycle lock held by another exec run\n"),
164
+ })
165
+ : undefined;
166
+ if (useWorktree && parallel > 1) {
167
+ // 並列実行: 成果物は worktree ごとに隔離し、状態遷移は lifecycleLock で直列化する。
168
+ // stop 指定でも実行中の項目は完走し、未着手の残りだけを skipped にする。
169
+ const queue = [...ids];
170
+ const byId = new Map();
171
+ let stop = false;
172
+ await runCompletionDrivenWorkerPool({
173
+ maxParallel: parallel,
174
+ fillSlots: (openSlots) => (stop ? [] : queue.splice(0, openSlots)),
175
+ runItem: (pjrId) => runItem(pjrId, lifecycleLock),
176
+ onSettled: (pjrId, summary) => {
177
+ byId.set(pjrId, summary);
178
+ if (summary.outcome === "failure" && failureMode === "stop") {
179
+ stop = true;
180
+ return { stop: true };
181
+ }
182
+ },
183
+ });
184
+ for (const pjrId of ids)
185
+ summaries.push(byId.get(pjrId) ?? skippedSummary(pjrId));
186
+ }
187
+ else {
188
+ let stopped = false;
189
+ for (const pjrId of ids) {
190
+ if (stopped) {
191
+ summaries.push(skippedSummary(pjrId));
192
+ continue;
193
+ }
194
+ const summary = useWorktree
195
+ ? await runItem(pjrId, lifecycleLock)
196
+ : await runSingleRegisterItem(context, optsForItem(pjrId), pjrId);
197
+ summaries.push(summary);
198
+ if (summary.outcome === "failure" && failureMode === "stop")
199
+ stopped = true;
200
+ }
201
+ }
202
+ process.stdout.write(`${formatRegisterRunSummary(summaries)}\n`);
203
+ const exitCode = registerRunExitCode(summaries);
204
+ if (exitCode !== 0)
205
+ process.exitCode = exitCode;
206
+ }
@@ -0,0 +1,393 @@
1
+ import { existsSync, readFileSync } from "node:fs";
2
+ import { resolve } from "node:path";
3
+ import { qualifyTaskId } from "./exec-shared.js";
4
+ import { requireRunnableRegisterItem, resolveRegisterRunTarget, sanitizeRegisterConclusion, ticketPathFromItem, } from "./exec-register.js";
5
+ import { readResultFrontmatterSnapshot } from "./exec-results.js";
6
+ import { findExecWorktree } from "./exec-worktree.js";
7
+ import { configuredProductRepos, missingProductWorktrees, withProductWorktrees, } from "./exec-task-repos.js";
8
+ import { currentBranch, isExecBranchMergedIntoCurrent } from "./exec-worktree-ops.js";
9
+ import { syncTaskWorktreesWithIntegrationTargets, } from "./exec-repo-integration.js";
10
+ import { failedParentValidationReason } from "./exec-parent-validation.js";
11
+ import { findResumableRegisterRun, resolveRegisterResumeArtifacts, } from "./exec-register-resume.js";
12
+ import { integratedRepoNames } from "./exec-pipeline-state.js";
13
+ import { resolveAgentOverride, } from "./exec-run-shared.js";
14
+ import { expandPromptRefs } from "./exec-run-agent.js";
15
+ import { refreshParentValidationsForReporterResume, runAgentPipeline, runReporterStage, } from "./exec-run-agent-pipeline.js";
16
+ import { repoRelativePath } from "./exec-run-mode-shared.js";
17
+ import { spawnRegisterTransition, registerReporterManagedPaths, } from "./exec-run-register-core.js";
18
+ import { copyRepoPaths, registerTransitionPaths, registerBookkeepingPaths, rebuildRootRegisterViews, } from "./exec-run-register-state.js";
19
+ import { finalizeRegisterWorktreeRun } from "./exec-run-register-worktree.js";
20
+ // reporter 再開に使う agent を解決する。--reporter-by を優先し、省略時は再開対象 run の
21
+ // pipeline-state に記録された reporter actor(通常は前回と同じ agent)へフォールバックする。
22
+ export function resolveRegisterResumeReporter(roster, opts, execDefaults, recordedActor) {
23
+ const nickname = (opts.reporterBy ?? recordedActor ?? "").trim();
24
+ if (!nickname) {
25
+ return {
26
+ kind: "error",
27
+ message: "reporter agent is unknown for this run; specify --reporter-by <nickname>",
28
+ };
29
+ }
30
+ const resolution = resolveAgentOverride("edit", nickname, {}, roster, execDefaults, "reporter");
31
+ if (resolution.kind === "error") {
32
+ return { kind: "error", message: resolution.message.replace(/^--by/, "--reporter-by") };
33
+ }
34
+ if (resolution.kind !== "command") {
35
+ return {
36
+ kind: "error",
37
+ message: `reporter agent not found in agent-members.yaml: ${nickname}`,
38
+ };
39
+ }
40
+ return {
41
+ kind: "command",
42
+ candidate: {
43
+ command: resolution.command,
44
+ actor: resolution.actor ?? nickname,
45
+ provider: resolution.provider,
46
+ },
47
+ };
48
+ }
49
+ // stale な running executor を既存 worktree 上で再実行するときの agent を解決する。
50
+ // --executor-by を優先し、省略時は pipeline-state に記録された actor を引き継ぐ。
51
+ export function resolveRegisterResumeExecutor(roster, opts, execDefaults, recordedActor) {
52
+ const nickname = (opts.executorBy ?? recordedActor ?? "").trim();
53
+ if (!nickname) {
54
+ return {
55
+ kind: "error",
56
+ message: "executor agent is unknown for this run; specify --executor-by <nickname>",
57
+ };
58
+ }
59
+ const resolution = resolveAgentOverride("edit", nickname, {}, roster, execDefaults, "executor");
60
+ if (resolution.kind === "error") {
61
+ return { kind: "error", message: resolution.message.replace(/^--by/, "--executor-by") };
62
+ }
63
+ if (resolution.kind !== "command") {
64
+ return {
65
+ kind: "error",
66
+ message: `executor agent not found in agent-members.yaml: ${nickname}`,
67
+ };
68
+ }
69
+ return {
70
+ kind: "command",
71
+ candidate: {
72
+ command: resolution.command,
73
+ actor: resolution.actor ?? nickname,
74
+ provider: resolution.provider,
75
+ },
76
+ };
77
+ }
78
+ // 統合段だけの再開。executor と reporter が成功済みで、commit → merge → worktree 撤去のいずれかが
79
+ // 失敗した run を、agent を1つも起動せずに統合からやり直す。worktree の成果物と evidence をそのまま
80
+ // 使い、成功なら通常実行と同じ review 遷移、merge 前の失敗なら waiting へ戻す。すでに merge
81
+ // 済みなら review を維持して cleanup だけを再試行する(失敗時も worktree は保持する)。
82
+ export async function resumeRegisterIntegration(params) {
83
+ const { item, worktree, target, worktreeResultPath, actor } = params;
84
+ process.stdout.write(`Register item: ${item.id} — ${item.title} [${item.type}]\n`);
85
+ process.stdout.write(` Resuming integration from run ${target.runId} (reporter result: ${params.stem}-result.md)\n` +
86
+ ` CWD: ${worktree.path}\n Actor: ${actor} (runner-owned integration)\n`);
87
+ // waiting のまま統合しないよう、通常実行と同じく in-progress へ戻してから統合する。ただし
88
+ // merge 済みで worktree 撤去だけを再試行する場合は、root はすでに review なので遷移を
89
+ // 再記録しない(finalize は cleanup だけを行う)。
90
+ let validationFailure;
91
+ if (!isExecBranchMergedIntoCurrent({
92
+ context: {
93
+ repoRoot: params.context.repoRoot,
94
+ schedulePath: params.context.schedulePath,
95
+ executionPath: params.context.executionPath,
96
+ },
97
+ worktree,
98
+ })) {
99
+ const beginFailure = await params.begin(actor, "integration resumed");
100
+ if (beginFailure)
101
+ return beginFailure;
102
+ // PJR-GENJ: 統合先の最新を取り込んだ worktree で親検証をやり直し、失敗なら統合せず waiting へ
103
+ // 戻す。前回の親検証が失敗・未記録の場合も同じく検証してから統合する。
104
+ if (target.stage === "integrate") {
105
+ const evidence = await refreshParentValidationsForReporterResume({
106
+ execDefaults: params.context.execDefaults,
107
+ cwd: worktree.path,
108
+ productWorktrees: worktree.repos,
109
+ evidence: target.evidence,
110
+ evidencePath: resolve(worktree.path, target.evidenceRef),
111
+ force: params.syncedIntegrationTargets,
112
+ stageLabel: "integration",
113
+ });
114
+ validationFailure = failedParentValidationReason(evidence.validations);
115
+ }
116
+ }
117
+ // reporter が記入済みの result をそのまま使う。agent は起動しないため、成果は success 扱いで
118
+ // 統合だけを実行する(result が未記入なら finalize 側の downgrade が blocked に落とす)。
119
+ const resultScaffold = readResultFrontmatterSnapshot(worktreeResultPath);
120
+ const finalize = async () => finalizeRegisterWorktreeRun({
121
+ context: params.context,
122
+ registerPaths: params.registerPaths,
123
+ item,
124
+ ticketPath: params.ticketPath,
125
+ worktree,
126
+ stem: params.stem,
127
+ worktreeResultPath,
128
+ resultScaffold,
129
+ agentResult: validationFailure ? "failure" : "success",
130
+ stderr: validationFailure ?? "",
131
+ ...(validationFailure ? { runnerBlockReason: validationFailure } : {}),
132
+ actor,
133
+ bookkeepingPaths: params.bookkeepingPaths(),
134
+ pipelineStatePath: target.statePath,
135
+ resumedIntegration: true,
136
+ });
137
+ return params.lifecycleLock ? params.lifecycleLock.runExclusive(finalize) : finalize();
138
+ }
139
+ // register 項目1件の再開。途中で止まった run を、既存 worktree と evidence を保持したまま
140
+ // 止まった段からやり直す。running のまま残った executor は同じ plan/result と worktree 上で
141
+ // 再実行し、reporter 段の再開は reporter だけを起動する。統合段は agent を起動せずに
142
+ // commit → merge → worktree 撤去だけをやり直す。入力は対象 run の
143
+ // `pipeline-state.json`(plan / result の参照と stage 状態)と `evidence.json`(executor の記録)で、
144
+ // 成功後の commit → merge → register review は通常実行と同じ finalizeRegisterWorktreeRun を通す。
145
+ // 再開できない場合(worktree 不在、入力成果物欠損など)は破壊的操作を行わず理由を返す。
146
+ export async function resumeSingleRegisterItemWorktree(context, opts, pjrId, lifecycleLock) {
147
+ const { projectId, schedulePath, executionPath, repoRoot } = context;
148
+ const { registerPaths, item } = resolveRegisterRunTarget(projectId, pjrId);
149
+ const ticketPath = ticketPathFromItem(item, registerPaths.projectRegisterPath);
150
+ requireRunnableRegisterItem(item);
151
+ // 再開できない場合は register の状態も worktree も変更せず、理由だけを返す。
152
+ const refuse = (reason) => {
153
+ process.stderr.write(`resume refused: ${item.id}: ${reason}\n`);
154
+ return {
155
+ id: item.id,
156
+ title: item.title,
157
+ outcome: "failure",
158
+ transition: "none",
159
+ commit: "off",
160
+ reason: sanitizeRegisterConclusion(reason),
161
+ };
162
+ };
163
+ const worktreeTaskId = qualifyTaskId(projectId, item.id);
164
+ const foundWorktree = findExecWorktree(repoRoot, worktreeTaskId);
165
+ if (!foundWorktree) {
166
+ return refuse(`no exec worktree to resume for ${item.id}; run the item again instead`);
167
+ }
168
+ // PJR-98G4: プロダクトの worktree も揃っていることを再開の条件にする。欠けたまま再開すると、
169
+ // agent がプロダクト側の変更先を失う。
170
+ const products = configuredProductRepos(schedulePath);
171
+ const worktree = withProductWorktrees(foundWorktree, products, worktreeTaskId);
172
+ const missingProducts = missingProductWorktrees(products, worktree);
173
+ if (missingProducts.length > 0) {
174
+ return refuse(`product worktrees are missing for ${item.id}: ${missingProducts.join(", ")}; ` +
175
+ `run the item again instead`);
176
+ }
177
+ const lookup = findResumableRegisterRun({
178
+ repoRoot,
179
+ worktreePath: worktree.path,
180
+ executionPath,
181
+ taskId: item.id,
182
+ ...(opts.resumeFrom === "executor" ? { resumeFrom: "executor" } : {}),
183
+ });
184
+ if (lookup.kind !== "resumable")
185
+ return refuse(lookup.reason);
186
+ const target = lookup.target;
187
+ const artifacts = resolveRegisterResumeArtifacts({
188
+ repoRoot,
189
+ worktreePath: worktree.path,
190
+ executionPath,
191
+ taskId: item.id,
192
+ state: target.state,
193
+ });
194
+ if (!artifacts)
195
+ return refuse(`cannot restore the plan/result of run ${target.runId}`);
196
+ const worktreeResultPath = resolve(worktree.path, artifacts.resultRef);
197
+ if (!existsSync(worktreeResultPath)) {
198
+ return refuse(`result not found in the worktree: ${artifacts.resultRef}`);
199
+ }
200
+ // root 側の実行管理ファイル。plan / result は前回の wait commit で統合ブランチに入っている。
201
+ // begin は個票と event を root へ写し、派生ビューを再生成する。その後の差分を拾うため、
202
+ // 再開開始前に集合を固定せず finalize の直前に評価する。
203
+ const bookkeepingPaths = () => registerBookkeepingPaths({
204
+ repoRoot,
205
+ registerPaths,
206
+ planPath: resolve(repoRoot, artifacts.planRef),
207
+ resultPath: resolve(repoRoot, artifacts.resultRef),
208
+ ticketPath,
209
+ });
210
+ // waiting のまま再開しないよう、通常実行と同じく in-progress へ戻す。遷移は exec branch
211
+ // 側の worktree で記録し(統合ブランチに独立した resume commit を作らない)、成功時は
212
+ // review とともに merge commit へ畳み込む。再び失敗した場合は finalize が start / wait を
213
+ // root の wait commit 1件へまとめる。root には個票・イベントを未 commit のまま写し、
214
+ // 実行中の状態が root からも見えるようにする(merge 前に解放する)。
215
+ const begin = async (actor, transitionReason) => {
216
+ const start = () => {
217
+ if (!spawnRegisterTransition(projectId, ["start", "--id", item.id, "--by", actor, "--reason", transitionReason], worktree.path)) {
218
+ return refuse(`register start failed: ${item.id}`);
219
+ }
220
+ copyRepoPaths(worktree.path, repoRoot, repoRoot, registerTransitionPaths(registerPaths, ticketPath));
221
+ rebuildRootRegisterViews(projectId, item.id);
222
+ return null;
223
+ };
224
+ return lifecycleLock ? lifecycleLock.runExclusive(start) : start();
225
+ };
226
+ // PJR-GENJ / PJR-PG6W: どの段の再開でも、親検証または agent の起動前に統合先の最新を exec
227
+ // branch と worktree へ取り込む。wait 後に統合先で直した不具合や、人が適用した保護対象設定を
228
+ // executor に反映するためである。register の遷移(begin)より前に行い、取り込めない場合は状態を
229
+ // 変えずに再開を拒否する。merge 済みで撤去だけが残る統合再開は取り込まない。
230
+ // PJR-6RN3: 前回の統合段で統合済み(merged / unchanged)と記録されたプロダクトも取り込まない。
231
+ // 取り込むと exec branch に新しい merge commit ができ、統合段がそのプロダクトを再び統合する。
232
+ let syncedIntegrationTargets = false;
233
+ if (!isExecBranchMergedIntoCurrent({
234
+ context: { repoRoot, schedulePath, executionPath },
235
+ worktree,
236
+ })) {
237
+ let synced;
238
+ try {
239
+ const projectTarget = currentBranch(repoRoot);
240
+ process.stdout.write(` Syncing integration targets before ${target.stage} resume: ${item.id}\n`);
241
+ synced = syncTaskWorktreesWithIntegrationTargets({
242
+ worktree,
243
+ projectTarget,
244
+ message: `exec(register ${item.id}): merge integration target before resume`,
245
+ projectTheirsPaths: bookkeepingPaths().map((path) => repoRelativePath(repoRoot, path)),
246
+ integratedProducts: integratedRepoNames(target.state),
247
+ });
248
+ }
249
+ catch (error) {
250
+ return refuse(`cannot sync the worktree with the integration target before resume: ` +
251
+ `${error instanceof Error ? error.message : String(error)}; ` +
252
+ `resolve it in ${worktree.path} and resume again`);
253
+ }
254
+ for (const entry of synced) {
255
+ process.stdout.write(` [sync] ${entry.repo}: ${entry.status} (${entry.target})` +
256
+ `${entry.detail ? ` — ${entry.detail}` : ""}\n`);
257
+ }
258
+ syncedIntegrationTargets = synced.some((entry) => entry.status === "merged");
259
+ }
260
+ if (target.stage === "integrate") {
261
+ // 統合は runner の作業だが、register の遷移とイベントには実行者が必要になる。前回 run の
262
+ // reporter(無ければ executor)を引き継ぎ、--reporter-by で明示指定もできる。
263
+ const actor = (opts.reporterBy ??
264
+ target.state.stages.reporter.actor ??
265
+ target.state.stages.executor.actor ??
266
+ "").trim();
267
+ if (!actor) {
268
+ return refuse(`the actor of run ${target.runId} is unknown; specify --reporter-by <nickname>`);
269
+ }
270
+ return resumeRegisterIntegration({
271
+ context,
272
+ registerPaths,
273
+ item,
274
+ ticketPath,
275
+ worktree,
276
+ target,
277
+ stem: artifacts.stem,
278
+ worktreeResultPath,
279
+ actor,
280
+ bookkeepingPaths,
281
+ begin,
282
+ lifecycleLock,
283
+ syncedIntegrationTargets,
284
+ });
285
+ }
286
+ // plan は root(統合ブランチ)の checkpoint 済みファイルを正本にする。worktree 側の plan は
287
+ // agent が書き換えられるため、再開のプロンプト入力には使わない。
288
+ const planPath = resolve(repoRoot, artifacts.planRef);
289
+ if (!existsSync(planPath))
290
+ return refuse(`plan not found for the resumed run: ${artifacts.planRef}`);
291
+ const prompt = expandPromptRefs(readFileSync(planPath, "utf8"));
292
+ if (target.stage === "executor") {
293
+ const executor = resolveRegisterResumeExecutor(context.roster, opts, context.execDefaults, target.state.stages.executor.actor);
294
+ if (executor.kind === "error")
295
+ return refuse(executor.message);
296
+ const reporter = resolveRegisterResumeReporter(context.roster, opts, context.execDefaults, target.state.stages.reporter.actor);
297
+ if (reporter.kind === "error")
298
+ return refuse(reporter.message);
299
+ process.stdout.write(`Register item: ${item.id} — ${item.title} [${item.type}]\n`);
300
+ process.stdout.write(` Resuming executor from run ${target.runId} in a new pipeline checkpoint\n` +
301
+ ` CWD: ${worktree.path}\n Agent: ${executor.candidate.actor} (executor)\n`);
302
+ const beginFailure = await begin(executor.candidate.actor, "executor resumed");
303
+ if (beginFailure)
304
+ return beginFailure;
305
+ const resultScaffold = readResultFrontmatterSnapshot(worktreeResultPath);
306
+ const outcome = await runAgentPipeline({
307
+ repoRoot,
308
+ cwd: worktree.path,
309
+ schedulePath,
310
+ executionPath,
311
+ taskId: item.id,
312
+ executor: executor.candidate,
313
+ reporterCandidates: [reporter.candidate],
314
+ planPath,
315
+ planPrompt: prompt,
316
+ resultPath: worktreeResultPath,
317
+ registerPaths: registerReporterManagedPaths(registerPaths),
318
+ execDefaults: context.execDefaults,
319
+ resumedExecutor: true,
320
+ initialChangeTargets: target.initialChanges,
321
+ resumeHandoff: target.handoff,
322
+ providerConcurrencyGate: context.providerConcurrencyGate,
323
+ productWorktrees: worktree.repos,
324
+ });
325
+ const finalize = async () => finalizeRegisterWorktreeRun({
326
+ context,
327
+ registerPaths,
328
+ item,
329
+ ticketPath,
330
+ worktree,
331
+ stem: artifacts.stem,
332
+ worktreeResultPath,
333
+ resultScaffold,
334
+ agentResult: outcome.runResult,
335
+ stderr: outcome.blockReason ?? "",
336
+ actor: executor.candidate.actor,
337
+ bookkeepingPaths: bookkeepingPaths(),
338
+ pipelineStatePath: resolve(worktree.path, outcome.stateRef),
339
+ });
340
+ return lifecycleLock ? lifecycleLock.runExclusive(finalize) : finalize();
341
+ }
342
+ const reporter = resolveRegisterResumeReporter(context.roster, opts, context.execDefaults, target.state.stages.reporter.actor);
343
+ if (reporter.kind === "error")
344
+ return refuse(reporter.message);
345
+ process.stdout.write(`Register item: ${item.id} — ${item.title} [${item.type}]\n`);
346
+ process.stdout.write(` Resuming reporter from run ${target.runId} (executor evidence: ${target.evidenceRef})\n` +
347
+ ` CWD: ${worktree.path}\n Agent: ${reporter.candidate.actor} (reporter)\n`);
348
+ const beginFailure = await begin(reporter.candidate.actor, "reporter resumed");
349
+ if (beginFailure)
350
+ return beginFailure;
351
+ const evidence = await refreshParentValidationsForReporterResume({
352
+ execDefaults: context.execDefaults,
353
+ cwd: worktree.path,
354
+ productWorktrees: worktree.repos,
355
+ evidence: target.evidence,
356
+ evidencePath: resolve(worktree.path, target.evidenceRef),
357
+ force: syncedIntegrationTargets,
358
+ });
359
+ const resultScaffold = readResultFrontmatterSnapshot(worktreeResultPath);
360
+ const outcome = await runReporterStage({
361
+ repoRoot,
362
+ cwd: worktree.path,
363
+ schedulePath,
364
+ executionPath,
365
+ reporterCandidates: [reporter.candidate],
366
+ planPrompt: prompt,
367
+ resultPath: worktreeResultPath,
368
+ registerPaths: registerReporterManagedPaths(registerPaths),
369
+ execDefaults: context.execDefaults,
370
+ evidence,
371
+ evidencePath: resolve(worktree.path, target.evidenceRef),
372
+ state: target.state,
373
+ statePath: target.statePath,
374
+ providerConcurrencyGate: context.providerConcurrencyGate,
375
+ productWorktrees: worktree.repos,
376
+ });
377
+ const finalize = async () => finalizeRegisterWorktreeRun({
378
+ context,
379
+ registerPaths,
380
+ item,
381
+ ticketPath,
382
+ worktree,
383
+ stem: artifacts.stem,
384
+ worktreeResultPath,
385
+ resultScaffold,
386
+ agentResult: outcome.runResult,
387
+ stderr: outcome.blockReason ?? "",
388
+ actor: reporter.candidate.actor,
389
+ bookkeepingPaths: bookkeepingPaths(),
390
+ pipelineStatePath: target.statePath,
391
+ });
392
+ return lifecycleLock ? lifecycleLock.runExclusive(finalize) : finalize();
393
+ }