specdojo 0.5.0 → 0.7.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 (137) hide show
  1. package/.github/agents/specdojo-orchestrator.md +2 -0
  2. package/CHANGELOG.md +100 -0
  3. package/README.md +2 -2
  4. package/dist/catalog/generate.js +144 -13
  5. package/dist/commands/agent.js +33 -0
  6. package/dist/commands/init.js +2 -0
  7. package/dist/commands/orchestrator.js +10 -1
  8. package/dist/deliverable/deliverable.js +77 -4
  9. package/dist/devcontainer/command.js +18 -0
  10. package/dist/devcontainer/host-script.js +21 -0
  11. package/dist/devcontainer/scaffold.js +4 -3
  12. package/dist/exec/antigravity-session.js +154 -0
  13. package/dist/exec/core.js +1 -0
  14. package/dist/exec/parent-validation.js +14 -0
  15. package/dist/exec/plan-markdownlint.js +89 -0
  16. package/dist/exec/plans-core.js +46 -1
  17. package/dist/exec/plans-generation.js +45 -5
  18. package/dist/exec/plans-planning.js +1 -1
  19. package/dist/exec/plans-storage.js +1 -0
  20. package/dist/exec/product-branch-records.js +105 -0
  21. package/dist/exec/product-branches.js +52 -0
  22. package/dist/exec/register-product-message.js +50 -0
  23. package/dist/exec/register-resume.js +28 -0
  24. package/dist/exec/register.js +6 -0
  25. package/dist/exec/repo-integration-sync.js +4 -2
  26. package/dist/exec/repo-integration.js +41 -4
  27. package/dist/exec/repo-trace.js +2 -0
  28. package/dist/exec/results.js +9 -5
  29. package/dist/exec/run/lifecycle-commands.js +85 -16
  30. package/dist/exec/run/register-command.js +22 -0
  31. package/dist/exec/run/register-resume.js +11 -1
  32. package/dist/exec/run/register-worktree.js +29 -8
  33. package/dist/exec/run/schedule-mode.js +22 -2
  34. package/dist/exec/run/schedule-prepare.js +49 -4
  35. package/dist/exec/run/schedule-task.js +3 -0
  36. package/dist/exec/strategy.js +2 -1
  37. package/dist/exec/task-repos.js +78 -16
  38. package/dist/exec/worktree-command.js +2 -2
  39. package/dist/exec/worktree-ops-commit.js +1 -13
  40. package/dist/exec/worktree-ops-lifecycle.js +40 -36
  41. package/dist/exec/worktree.js +3 -3
  42. package/dist/register/core.js +5 -0
  43. package/dist/register/create-commands.js +54 -2
  44. package/dist/register/deliverable-target.js +24 -17
  45. package/dist/register/event-merge.js +4 -0
  46. package/dist/register/events.js +6 -0
  47. package/dist/register/external-project.js +2 -0
  48. package/dist/register/input.js +168 -0
  49. package/dist/register/item.js +61 -0
  50. package/dist/register/register.js +33 -25
  51. package/dist/register/renumber.js +4 -0
  52. package/dist/register/update.js +6 -0
  53. package/dist/schedule/approach.js +9 -0
  54. package/dist/schedule/strategy-profiles.js +22 -2
  55. package/dist/shared/agent-types.js +4 -1
  56. package/dist/shared/branch-template.js +26 -0
  57. package/dist/shared/commit-message-template.js +38 -0
  58. package/dist/shared/commit-types.js +15 -0
  59. package/dist/shared/git.js +7 -0
  60. package/dist/shared/provider-scaffold.js +2 -0
  61. package/dist/shared/specdojo-config.js +35 -4
  62. package/dist/shared/specdojo-gitignore.js +1 -0
  63. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +2 -0
  64. package/docs/ja/specdojo/exec-templates/xep-draft-template.md +93 -0
  65. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +9 -2
  66. package/docs/ja/specdojo/exec-templates/xep-register-investigate-template.md +2 -0
  67. package/docs/ja/specdojo/exec-templates/xep-register-template.md +2 -0
  68. package/docs/ja/specdojo/exec-templates/xer-human-bootstrap-finalize-template.md +2 -0
  69. package/docs/ja/specdojo/exec-templates/xer-human-draft-template.md +23 -0
  70. package/docs/ja/specdojo/exec-templates/xer-human-finalize-template.md +2 -0
  71. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +7 -4
  72. package/docs/ja/specdojo/guides/docs-editing-guide.md +36 -0
  73. package/docs/ja/specdojo/guides/exec-config-guide.md +16 -12
  74. package/docs/ja/specdojo/guides/exec-operation-guide.md +116 -10
  75. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +4 -2
  76. package/docs/ja/specdojo/guides/quick-start-guide.md +597 -871
  77. package/docs/ja/specdojo/guides/register-operation-guide.md +16 -1
  78. package/docs/ja/specdojo/guides/remote-host-development-guide.md +31 -4
  79. package/docs/ja/specdojo/guides/ryu-guide.md +114 -23
  80. package/docs/ja/specdojo/guides/schedule-design-guide.md +31 -4
  81. package/docs/ja/specdojo/guides/schedule-operation-guide.md +14 -0
  82. package/docs/ja/specdojo/guides/use-case-guide.md +537 -77
  83. package/docs/ja/specdojo/recipes/cdfd-overview-recipe.md +88 -86
  84. package/docs/ja/specdojo/recipes/cdfd-uc-recipe.md +96 -122
  85. package/docs/ja/specdojo/recipes/exec-human-finalize-recipe.md +1 -0
  86. package/docs/ja/specdojo/recipes/tsd-recipe.md +20 -12
  87. package/docs/ja/specdojo/references/command-reference.md +111 -46
  88. package/docs/ja/specdojo/references/specdojo-config-reference.md +69 -8
  89. package/docs/ja/specdojo/rulebooks/cdfd-d2-rulebook.md +367 -0
  90. package/docs/ja/specdojo/rulebooks/cdfd-mermaid-rulebook.md +6 -5
  91. package/docs/ja/specdojo/rulebooks/cdfd-overview-rulebook.md +96 -100
  92. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +38 -47
  93. package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +108 -103
  94. package/docs/ja/specdojo/rulebooks/dct-rulebook.md +8 -0
  95. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +4 -0
  96. package/docs/ja/specdojo/rulebooks/sch-rulebook.md +3 -1
  97. package/docs/ja/specdojo/samples/cdfd-overview-sample.md +248 -140
  98. package/docs/ja/specdojo/samples/cdfd-uc-sample.md +128 -97
  99. package/docs/ja/specdojo/samples/dct-sample.yaml +5 -1
  100. package/docs/ja/specdojo/standards/document-metadata-standard.md +16 -0
  101. package/docs/ja/specdojo/standards/exec-human-finalize-standard.md +1 -0
  102. package/docs/ja/specdojo/standards/guide-authoring-standard.md +2 -1
  103. package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +1 -0
  104. package/docs/ja/specdojo/standards/recipe-authoring-standard.md +2 -1
  105. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +2 -1
  106. package/docs/ja/specdojo/standards/standard-authoring-standard.md +2 -1
  107. package/docs/ja/specdojo/templates/cdfd-overview-template.md +161 -83
  108. package/docs/ja/specdojo/templates/cdfd-uc-template.md +127 -90
  109. package/docs/ja/specdojo/templates/pjr-change-request-template.md +10 -4
  110. package/docs/ja/specdojo/templates/pjr-issue-template.md +10 -4
  111. package/docs/ja/specdojo/templates/pjr-question-template.md +11 -5
  112. package/docs/ja/specdojo/templates/pjr-risk-template.md +10 -4
  113. package/docs/ja/specdojo/templates/pjr-todo-template.md +10 -4
  114. package/docs/specdojo/schemas/v1/dct.schema.yaml +9 -0
  115. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +2 -1
  116. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +2 -0
  117. package/docs/specdojo/schemas/v1/register-events.schema.yaml +3 -0
  118. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +35 -0
  119. package/docs/specdojo/schemas/v1/sch-strategy.schema.yaml +1 -0
  120. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +41 -2
  121. package/package.json +6 -2
  122. package/templates/antigravity/README.md +19 -46
  123. package/templates/antigravity/exec-defaults-snippet.yaml +5 -6
  124. package/templates/antigravity/orchestrator.md +2 -0
  125. package/templates/antigravity/settings.edit.json +73 -0
  126. package/templates/antigravity/settings.orchestrator.json +15 -0
  127. package/templates/antigravity/settings.report.json +7 -0
  128. package/templates/antigravity/settings.review.json +7 -0
  129. package/templates/claude/agents/specdojo-orchestrator.md +2 -0
  130. package/templates/codex/agents/specdojo-orchestrator.toml +2 -0
  131. package/templates/codex/orchestrator.md +2 -0
  132. package/templates/devcontainer/remote-host/devcontainer-tmux.sh +217 -0
  133. package/templates/devcontainer/remote-host/specdojo-tmux.sh.sample +8 -90
  134. package/templates/devcontainer/remote-host/ssh-config.sample +3 -1
  135. package/templates/init-agent-members.yaml +1 -0
  136. package/templates/init-exec-defaults.yaml +1 -1
  137. package/templates/opencode/agents/specdojo-orchestrator.md +2 -0
@@ -0,0 +1,52 @@
1
+ import { basename } from "node:path";
2
+ import { resolveItemCommitTypeAndScope } from "../register/item.js";
3
+ import { DEFAULT_BRANCH_TEMPLATE, expandBranchTemplate } from "../shared/branch-template.js";
4
+ import { worktreeNameFromTaskId } from "./worktree.js";
5
+ import { assertProductBranchAvailable, recordedProductBranch } from "./product-branch-records.js";
6
+ import { parseIntegrationBranchOverrides } from "./task-repos.js";
7
+ export function parseProductBranchOverrides(values) {
8
+ try {
9
+ return parseIntegrationBranchOverrides(values);
10
+ }
11
+ catch (error) {
12
+ throw new Error((error instanceof Error ? error.message : String(error)).replaceAll("--integration-branch", "--branch"));
13
+ }
14
+ }
15
+ /** Resolve and preflight names before register start or stale-worktree removal. */
16
+ export function resolveProductBranches(products, params) {
17
+ const overrides = parseProductBranchOverrides(params.overrides);
18
+ for (const repo of overrides.keys()) {
19
+ if (!products.some((product) => product.name === repo)) {
20
+ throw new Error(`--branch references undeclared product repository: ${repo}`);
21
+ }
22
+ }
23
+ return products.map((product) => {
24
+ const persisted = recordedProductBranch(product.repoRoot, params.taskId);
25
+ const override = overrides.get(product.name);
26
+ const resumedBranch = persisted ?? `exec/${worktreeNameFromTaskId(params.taskId)}`;
27
+ if (params.resume && override && override !== resumedBranch) {
28
+ throw new Error(`--branch cannot change the resumed run branch for ${product.name}: ${resumedBranch}`);
29
+ }
30
+ const { type, scope } = resolveItemCommitTypeAndScope(params.item, {
31
+ projectConfig: params.projectConfig,
32
+ repoConfig: params.projectConfig?.repos?.find((repo) => repo.name === product.name),
33
+ });
34
+ const topic = params.ticketPath
35
+ ? basename(params.ticketPath)
36
+ .replace(/^pjr-[a-z0-9]{4}-/, "")
37
+ .replace(/\.md$/, "")
38
+ : params.item.id.toLowerCase();
39
+ const branch = (params.resume ? resumedBranch : undefined) ??
40
+ override ??
41
+ expandBranchTemplate(product.branchTemplate ?? DEFAULT_BRANCH_TEMPLATE, {
42
+ project: params.projectId,
43
+ id: params.item.id,
44
+ topic,
45
+ type,
46
+ scope: scope ?? "",
47
+ title: params.item.title.replace(/\s+/g, " ").trim(),
48
+ });
49
+ assertProductBranchAvailable(product.repoRoot, params.taskId, branch);
50
+ return { ...product, branch };
51
+ });
52
+ }
@@ -0,0 +1,50 @@
1
+ import { basename } from "node:path";
2
+ import { resolveItemCommitTypeAndScope } from "../register/item.js";
3
+ import { expandCommitMessageTemplate } from "../shared/commit-message-template.js";
4
+ import { commitSubject } from "./run/mode-shared.js";
5
+ import { refsTrailer } from "./repo-trace.js";
6
+ import { productIntegrationTarget } from "./task-repos.js";
7
+ /** Build only product messages; project bookkeeping keeps its existing subjects. */
8
+ export function registerProductMessage(params) {
9
+ const { item, projectId, repoConfig, product } = params;
10
+ const template = params.kind === "commit"
11
+ ? repoConfig?.commit_subject_template
12
+ : repoConfig?.merge_message_template;
13
+ const { type, scope } = resolveItemCommitTypeAndScope(item, {
14
+ projectConfig: params.projectConfig,
15
+ repoConfig,
16
+ });
17
+ const topic = params.ticketPath
18
+ ? basename(params.ticketPath)
19
+ .replace(/^pjr-[a-z0-9]{4}-/, "")
20
+ .replace(/\.md$/, "")
21
+ : item.id.toLowerCase();
22
+ const expanded = template === undefined
23
+ ? commitSubject(`exec(register ${item.id}): `, item.title)
24
+ : expandCommitMessageTemplate(template, {
25
+ id: item.id,
26
+ project: projectId,
27
+ topic,
28
+ type,
29
+ scope: scope ?? "",
30
+ title: item.title.replace(/\s+/g, " ").trim(),
31
+ branch: product.branch,
32
+ target: productIntegrationTarget(product),
33
+ });
34
+ // Commit templates are subjects; merge templates may also provide a body.
35
+ const [first = "", ...body] = expanded.replace(/\r\n?/g, "\n").trim().split("\n");
36
+ const message = params.kind === "commit"
37
+ ? commitSubject("", expanded)
38
+ : [commitSubject("", first), ...body].join("\n");
39
+ const trailer = refsTrailer(projectId, item.id);
40
+ // Keep exactly one required trailer at the end, even if the template supplied it earlier.
41
+ const withoutTrailer = message
42
+ .split("\n")
43
+ .filter((line) => line.trim() !== trailer)
44
+ .join("\n")
45
+ .trimEnd();
46
+ if (!withoutTrailer.split("\n")[0]?.trim()) {
47
+ throw new Error(`${product.name}: ${params.kind} message template expanded to an empty subject`);
48
+ }
49
+ return `${withoutTrailer}\n\n${trailer}`;
50
+ }
@@ -197,6 +197,34 @@ export function selectResumableRegisterRun(candidates, options = {}) {
197
197
  export function findResumableRegisterRun(input) {
198
198
  return selectResumableRegisterRun(loadRegisterResumeCandidates(input), input.resumeFrom ? { resumeFrom: input.resumeFrom } : {});
199
199
  }
200
+ // Schedule の明示的な executor 再開は、成功済み executor から reporter へ進んだ run に限る。
201
+ // run の選択・変更一覧・申し送りの復元は register と同じ規則を使う。
202
+ export function selectScheduleExecutorResume(candidates) {
203
+ const lookup = selectResumableRegisterRun(candidates, { resumeFrom: "executor" });
204
+ if (lookup.kind !== "resumable")
205
+ return lookup;
206
+ const { state } = lookup.target;
207
+ if (state.stages.executor.status !== "succeeded") {
208
+ return {
209
+ kind: "not-resumable",
210
+ reason: `--resume-from executor requires a succeeded executor stage for run ${state.run_id} (status: ${state.stages.executor.status})`,
211
+ };
212
+ }
213
+ const candidate = candidates.find((entry) => entry.runId === lookup.target.runId && entry.stateRef === lookup.target.stateRef);
214
+ if ((candidate?.executorEvidence ?? candidate?.evidence)?.stage.status !== "succeeded") {
215
+ return {
216
+ kind: "not-resumable",
217
+ reason: `succeeded executor evidence is missing or invalid for run ${state.run_id}`,
218
+ };
219
+ }
220
+ if (state.stages.reporter.status === "succeeded" || (state.stages.integrate?.attempts ?? 0) > 0) {
221
+ return {
222
+ kind: "not-resumable",
223
+ reason: `cannot resume the executor from the integrate stage of run ${state.run_id}`,
224
+ };
225
+ }
226
+ return lookup;
227
+ }
200
228
  // plan / result のファイル名は `<pjr-id>-<UTC>-<rand>-(plan|result).md`(buildInPlaceStem)。
201
229
  // state に artifacts が無い旧 run のために、worktree の result 一覧から最新の stem を復元する。
202
230
  export function selectLatestRegisterResultStem(fileNames, pjrId) {
@@ -1,3 +1,4 @@
1
+ import { readRegisterInput, registerInputSection } from "../register/input.js";
1
2
  import { resolveRegisterDeliverableTarget, } from "../register/deliverable-target.js";
2
3
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
3
4
  import { basename, extname, join, relative, resolve } from "node:path";
@@ -376,6 +377,9 @@ export async function generateRegisterPlan(opts) {
376
377
  const { item } = opts;
377
378
  const category = requireRunnableRegisterItem(item);
378
379
  const ticketPath = ticketPathFromItem(item, opts.registerPaths.projectRegisterPath);
380
+ const inputs = ticketPath && existsSync(ticketPath)
381
+ ? readRegisterInput(readFileSync(ticketPath, "utf8"))
382
+ : item.inputs;
379
383
  if (item.approach) {
380
384
  validateRegisterApproachTargets({
381
385
  repoRoot: specdojoRootDir(),
@@ -508,6 +512,7 @@ export async function generateRegisterPlan(opts) {
508
512
  deliverable,
509
513
  ...(refs ? { refs } : {}),
510
514
  ...(authoring ? { authoring } : {}),
515
+ registerInput: inputs,
511
516
  additionalConditions: [
512
517
  cataloglessConditions,
513
518
  registerCompletionConditions(item, ticketPath),
@@ -545,6 +550,7 @@ export async function generateRegisterPlan(opts) {
545
550
  _PJR_DUE_: item.due,
546
551
  _PJR_TICKET_REF_: ticketPath ? `\`${repoRelativePath(ticketPath)}\`` : "-",
547
552
  _RESULT_REF_: resultRef,
553
+ _REGISTER_INPUT_: registerInputSection(inputs),
548
554
  _GRADE_FINDINGS_: ticketPath ? registerGradeFindingsText(opts.projectId, ticketPath) : "- なし",
549
555
  _AUTOPILOT_CONSTRAINTS_: registerAutopilotConstraints(item),
550
556
  };
@@ -229,12 +229,14 @@ export function syncTaskWorktreesWithIntegrationTargets(params) {
229
229
  const synced = [];
230
230
  for (const product of params.worktree.repos ?? []) {
231
231
  const target = productIntegrationTarget(product);
232
- if (product.integrationStrategy === "branch-only") {
232
+ if (product.integrationStrategy === "branch-only" || product.integrationStrategy === "ff") {
233
233
  synced.push({
234
234
  repo: product.name,
235
235
  target,
236
236
  status: "skipped",
237
- detail: "product-side review (branch-only)",
237
+ detail: product.integrationStrategy === "ff"
238
+ ? "fast-forward only (ff)"
239
+ : "product-side review (branch-only)",
238
240
  });
239
241
  continue;
240
242
  }
@@ -1,3 +1,4 @@
1
+ import { productBranchRecords } from "./product-branch-records.js";
1
2
  import { appendFileSync, existsSync, mkdirSync } from "node:fs";
2
3
  import { dirname, resolve } from "node:path";
3
4
  import { acquireSchedulerLock, releaseSchedulerLock } from "./events.js";
@@ -148,7 +149,7 @@ export function commitProductWorktrees(params) {
148
149
  if (!existsSync(product.path))
149
150
  continue;
150
151
  const outcome = commitProductWorktree(product, {
151
- message: params.message,
152
+ message: typeof params.message === "function" ? params.message(product) : params.message,
152
153
  targetPaths: targetPaths.get(product.name),
153
154
  failureLogPath: params.failureLogPath,
154
155
  });
@@ -198,6 +199,11 @@ export function productMergeState(product) {
198
199
  ]);
199
200
  if (ancestor.status !== 0)
200
201
  return "pending";
202
+ if (product.integrationStrategy === "ff") {
203
+ const record = productBranchRecords(product.repoRoot).find((entry) => entry.branch === product.branch);
204
+ if (record?.startCommit)
205
+ return record.startCommit === gitText(tip.stdout).trim() ? "unchanged" : "merged";
206
+ }
201
207
  const firstParent = gitOutput(product.repoRoot, ["rev-list", "--first-parent", target])
202
208
  .split("\n")
203
209
  .map((line) => line.trim());
@@ -261,6 +267,12 @@ export function productMergeBlockers(product) {
261
267
  }
262
268
  if (productMergeState(product) !== "pending")
263
269
  return blockers;
270
+ if (product.integrationStrategy === "ff" &&
271
+ gitResult(product.repoRoot, ["merge-base", "--is-ancestor", target, product.branch]).status !==
272
+ 0) {
273
+ blockers.push(block(`cannot fast-forward ${target} to ${product.branch}: histories have diverged; no rebase or merge is performed`));
274
+ return blockers;
275
+ }
264
276
  const merged = mergeTree(product.repoRoot, target, product.branch);
265
277
  if (merged.kind === "conflicts") {
266
278
  blockers.push(block(`merge conflicts with ${target}: ${merged.paths.join(", ")}`));
@@ -329,8 +341,8 @@ export function projectMergeBlockers(params) {
329
341
  }
330
342
  // ── プロダクトの merge ─────────────────────────────────────────────────────
331
343
  /**
332
- * Merge the product exec branch into its integration target with a merge commit and return the
333
- * merge commit. When the target is checked out (normally the product's main checkout), a regular
344
+ * Integrate the product branch and return the resulting tip. The ff strategy only advances the
345
+ * target to the product tip, without creating a commit. For merge, when the target is checked out,
334
346
  * `git merge --no-ff` updates that working tree; a failed merge is aborted. Otherwise the merge
335
347
  * commit is written with `merge-tree` / `commit-tree` and the branch is moved with a
336
348
  * compare-and-swap `update-ref`, so a concurrent update of the target is never overwritten.
@@ -340,6 +352,29 @@ export function mergeProductIntoTarget(params) {
340
352
  const target = productIntegrationTarget(product);
341
353
  const checkout = checkoutOfBranch(product.repoRoot, target);
342
354
  const header = `=== ${new Date().toISOString()} ${product.name}: merge ${product.branch} into ${target} ===`;
355
+ if (product.integrationStrategy === "ff") {
356
+ const parent = gitOutput(product.repoRoot, ["rev-parse", `refs/heads/${target}`]).trim();
357
+ const tip = gitOutput(product.repoRoot, ["rev-parse", `${product.branch}^{commit}`]).trim();
358
+ if (gitResult(product.repoRoot, ["merge-base", "--is-ancestor", parent, tip]).status !== 0) {
359
+ throw new Error(`cannot fast-forward ${target} to ${product.branch}: histories have diverged; no rebase or merge is performed`);
360
+ }
361
+ const result = checkout
362
+ ? gitResult(checkout, ["merge", "--ff-only", tip])
363
+ : gitResult(product.repoRoot, [
364
+ "update-ref",
365
+ "-m",
366
+ `exec: fast-forward ${product.branch}`,
367
+ `refs/heads/${target}`,
368
+ tip,
369
+ parent,
370
+ ]);
371
+ if (result.status !== 0) {
372
+ const detail = gitText(result.stderr).trim() || gitText(result.stdout).trim();
373
+ appendGitFailureLog(params.failureLogPath, [header, `fast-forward failed: ${detail}`, ""]);
374
+ throw new Error(`cannot fast-forward ${target} to ${product.branch}: ${detail}`);
375
+ }
376
+ return tip;
377
+ }
343
378
  if (checkout) {
344
379
  const result = gitResult(checkout, ["merge", "--no-ff", "-m", message, product.branch]);
345
380
  if (result.status === 0)
@@ -519,7 +554,9 @@ export function integrateTaskRepositories(params) {
519
554
  }
520
555
  commit = mergeProductIntoTarget({
521
556
  product,
522
- message: params.productMergeMessage ?? params.mergeMessage,
557
+ message: typeof params.productMergeMessage === "function"
558
+ ? params.productMergeMessage(product)
559
+ : (params.productMergeMessage ?? params.mergeMessage),
523
560
  failureLogPath: params.failureLogPath,
524
561
  });
525
562
  }
@@ -46,6 +46,8 @@ function integrationCommitOf(product, target) {
46
46
  if (tip.status !== 0)
47
47
  return null;
48
48
  const tipSha = String(tip.stdout).trim();
49
+ if (product.integrationStrategy === "ff")
50
+ return tipSha;
49
51
  const lines = gitOutput(product.repoRoot, [
50
52
  "rev-list",
51
53
  "--first-parent",
@@ -105,9 +105,12 @@ function execResultDocId(projectId, mode, localBase) {
105
105
  const localId = `${prefix}-${localBase.toLowerCase()}`;
106
106
  return projectId ? `${projectId}:${localId}` : localId;
107
107
  }
108
- // approach が finalize 系なら xer-human-<approach>-template.md を優先し、無ければ
109
- // mode 別の標準テンプレートへフォールバックする(plan 側の human × approach 解決と対称)。
110
- function loadResultTemplate(mode, approach) {
108
+ // Human draft results guide scaffold/context entry; finalize results guide confirmation.
109
+ // Other approaches use their specialized result or the standard mode template.
110
+ function loadResultTemplate(mode, approach, execution) {
111
+ if (mode === "edit" && execution === "human" && approach === "draft") {
112
+ return readFileSync(resolveSpecdojoPath("docs/ja/specdojo/exec-templates/xer-human-draft-template.md"), "utf8");
113
+ }
111
114
  if (mode === "edit" && approach === "cross-deliverable-dedup") {
112
115
  const crossDeliverablePath = resolveSpecdojoPathIfExists("docs/ja/specdojo/exec-templates/xer-cross-deliverable-dedup-template.md");
113
116
  if (crossDeliverablePath)
@@ -160,7 +163,7 @@ async function supersedePriorResults(resultsDir, taskId, nextResultPath, superse
160
163
  const APPROACH_SECTION_WITH_APPROACH = [
161
164
  "## 4. 進め方と実践の型の適用",
162
165
  "",
163
- "_TODO_: `approach` に従ってどう進めたか、その進め方の中で実践の型(rulebook / recipe / sample / template)をどう適用したかを記入する(`fully-guided` で rulebook / recipe / sample / template をどう使い分けたか、`recipe-guided` で recipe のみを基準にした内容、`freeform` で実践の型より優先した実例やプロジェクト文脈、`retrofit` で実際に参照した実装パス・抽出した現在動作・反映/新設判断・未反映の乖離・未確認範囲、`rulebook-authoring` などの authoring 系で手本から一般化した内容・変更しなかった手本・参照の付け替えまたは見送り、`rulebook-maintenance` などの maintenance 系で見直した実践の型とその根拠、など)。実践の型を基準にしなかった場合は、その判断と代わりに根拠にした内容も記入する。複数文書間に矛盾があり rulebook を正として判断した箇所、参照範囲から外れていた文書とその代わりに根拠にした内容があれば、あわせて記録する。",
166
+ "_TODO_: `approach` に従ってどう進めたか、その進め方の中で実践の型(rulebook / recipe / sample / template)をどう適用したかを記入する(`draft` で任された範囲・提案値ごとの出典と選定理由・反映した元の指示、`fully-guided` で rulebook / recipe / sample に沿って既存成果物をどう磨き込んだか、`recipe-guided` で recipe のみを基準にした内容、`freeform` で実践の型より優先した実例やプロジェクト文脈、`retrofit` で実際に参照した実装パス・抽出した現在動作・反映/新設判断・未反映の乖離・未確認範囲、`rulebook-authoring` などの authoring 系で手本から一般化した内容・変更しなかった手本・参照の付け替えまたは見送り、`rulebook-maintenance` などの maintenance 系で見直した実践の型とその根拠、など)。実践の型を基準にしなかった場合は、その判断と代わりに根拠にした内容も記入する。複数文書間に矛盾があり rulebook を正として判断した箇所、参照範囲から外れていた文書とその代わりに根拠にした内容があれば、あわせて記録する。",
164
167
  ].join("\n");
165
168
  const APPROACH_SECTION_WITHOUT_APPROACH = [
166
169
  "## 4. 進め方",
@@ -178,7 +181,7 @@ export async function scaffoldResult(opts) {
178
181
  const resultsDir = join(executionPath, "exec", "results");
179
182
  if (!existsSync(resultsDir))
180
183
  mkdirSync(resultsDir, { recursive: true });
181
- const template = loadResultTemplate(mode, approach);
184
+ const template = loadResultTemplate(mode, approach, opts.execution);
182
185
  const meta = {
183
186
  id: execResultDocId(projectId, mode, stem),
184
187
  type: "exec-result",
@@ -770,6 +773,7 @@ export function parseResultTaskIdentity(resultContent) {
770
773
  const execution = meta.execution === "human" || meta.execution === "agent" ? meta.execution : undefined;
771
774
  const approach = meta.approach &&
772
775
  [
776
+ "draft",
773
777
  "fully-guided",
774
778
  "recipe-guided",
775
779
  "freeform",
@@ -16,6 +16,7 @@ import { findExecWorktree, resolveWorktreeBase } from "../worktree.js";
16
16
  import { configuredProductRepos, withProductWorktrees } from "../task-repos.js";
17
17
  import { parentValidationPoolPath, resolveParentValidationConcurrency, } from "../parent-validation.js";
18
18
  import { loadPipelineResumeCheckpoint } from "../pipeline-state.js";
19
+ import { loadRegisterResumeCandidates, selectScheduleExecutorResume, } from "../register-resume.js";
19
20
  import { buildTaskPhaseMap, configuredWorktreeBase, parseParallel, resolveExecDefaultsPath, withProjectExecRunLock, } from "./shared.js";
20
21
  import { loadRosterForExecutionPath, pathInsideWorktree } from "./agent.js";
21
22
  import { findClaimEventPath, prepareSingleTask, } from "./schedule-prepare.js";
@@ -295,12 +296,22 @@ export function prepareScheduleIntegrationResume(params) {
295
296
  pipelineStateRef: stateRef,
296
297
  };
297
298
  }
299
+ function validateScheduleResumeOptions(opts) {
300
+ if (opts.resumeFrom !== undefined) {
301
+ if (opts.resumeFrom !== "executor")
302
+ throw new Error('--resume-from must be "executor".');
303
+ if (!opts.task || opts.due) {
304
+ throw new Error("--resume-from requires --task and cannot be combined with --due.");
305
+ }
306
+ }
307
+ }
298
308
  // Resume tasks left in "doing" state by an interrupted run. Unlike --auto (which selects from
299
309
  // ready.json and provably excludes "doing"/"blocked" tasks), resume folds the event log to find
300
310
  // in-flight tasks and re-runs each on its existing worktree, reusing the claiming actor and the
301
311
  // partially-filled result (scaffoldResult is idempotent; the worktree is reused). No validate/build
302
312
  // pass — selection comes from events, not the generated cache.
303
313
  export async function runResumeMode(opts) {
314
+ validateScheduleResumeOptions(opts);
304
315
  const resolvedPaths = resolveProjectPaths({ project: opts.project });
305
316
  activateResolvedProjectPaths(resolvedPaths);
306
317
  const { schedulePath, executionPath, catalogPath, rolesPath, viewpointsPath, projectContext } = resolvedPaths;
@@ -320,6 +331,40 @@ export async function runResumeMode(opts) {
320
331
  const initTasks = buildInitialStateFromStrategy(schedulePath, schedule);
321
332
  let snapshot = foldEventsToState(events, schedule, schedulePath, initTasks);
322
333
  let doingIds;
334
+ let executorResume;
335
+ let executorWorktree;
336
+ let pendingExecutorUnblock;
337
+ // Validate before changing lifecycle state or generating a plan. Interrupted doing tasks may
338
+ // have no block metadata, so discover their latest run in the existing worktree as register does.
339
+ if (opts.resumeFrom === "executor" && opts.task) {
340
+ const task = buildTaskView(schedulePath, executionPath, opts.task);
341
+ if (!task.agent_pipeline)
342
+ throw new Error("--resume-from requires an agent_pipeline task.");
343
+ const taskState = snapshot.tasks[opts.task];
344
+ if (taskState?.meta?.pipeline_stage === "integrate") {
345
+ throw new Error("cannot resume the executor from the integrate stage");
346
+ }
347
+ if (taskState?.state !== "doing" &&
348
+ !(taskState?.state === "blocked" && taskState.meta?.pipeline_stage === "reporter")) {
349
+ throw new Error("--resume-from executor requires a doing task or a blocked reporter stage.");
350
+ }
351
+ const worktreeTaskId = qualifyTaskId(projectId, opts.task);
352
+ const found = findExecWorktree(repoRoot, worktreeTaskId);
353
+ if (!found)
354
+ throw new Error(`no exec worktree to resume executor for ${opts.task}`);
355
+ const lookup = selectScheduleExecutorResume(loadRegisterResumeCandidates({
356
+ repoRoot,
357
+ worktreePath: found.path,
358
+ executionPath,
359
+ taskId: opts.task,
360
+ }));
361
+ if (lookup.kind !== "resumable")
362
+ throw new Error(lookup.reason);
363
+ if (lookup.target.stage !== "executor")
364
+ throw new Error("no executor stage to resume");
365
+ executorResume = lookup.target;
366
+ executorWorktree = withProductWorktrees(found, configuredProductRepos(schedulePath), worktreeTaskId);
367
+ }
323
368
  if (opts.due) {
324
369
  let lockDir = "";
325
370
  try {
@@ -382,18 +427,30 @@ export async function runResumeMode(opts) {
382
427
  if (canResumeBlockedPipeline) {
383
428
  const actor = taskState.last_by ?? opts.by ?? "exec-pipeline-resume";
384
429
  if (!dryRun) {
385
- const meta = Object.entries(taskState.meta ?? {}).map(([key, value]) => `${key}=${String(value)}`);
430
+ const resumeMeta = {
431
+ ...taskState.meta,
432
+ ...(executorResume
433
+ ? { pipeline_stage: "executor", pipeline_state_ref: executorResume.stateRef }
434
+ : {}),
435
+ };
436
+ const meta = Object.entries(resumeMeta).map(([key, value]) => `${key}=${String(value)}`);
386
437
  meta.push("pipeline_resume_claimed=true");
387
- writeEventFile(schedulePath, buildEvent("unblock", {
438
+ const event = buildEvent("unblock", {
388
439
  task: opts.task,
389
440
  by: actor,
390
- msg: blockedPipelineStage === "integrate"
391
- ? "resume integration from persisted pipeline state"
392
- : blockedPipelineStage === "reporter"
393
- ? "resume reporter from persisted pipeline state"
394
- : "resume executor from persisted pipeline state",
441
+ msg: opts.resumeFrom === "executor"
442
+ ? "resume executor from persisted pipeline state (--resume-from executor)"
443
+ : blockedPipelineStage === "integrate"
444
+ ? "resume integration from persisted pipeline state"
445
+ : blockedPipelineStage === "reporter"
446
+ ? "resume reporter from persisted pipeline state"
447
+ : "resume executor from persisted pipeline state",
395
448
  meta,
396
- }));
449
+ });
450
+ if (executorResume)
451
+ pendingExecutorUnblock = event;
452
+ else
453
+ writeEventFile(schedulePath, event);
397
454
  }
398
455
  snapshot.tasks[opts.task] = {
399
456
  ...taskState,
@@ -438,16 +495,26 @@ export async function runResumeMode(opts) {
438
495
  })
439
496
  : await prepareSingleTask(task, projectId, repoRoot, schedulePath, executionPath, roster, localIdToPhaseSets, phaseSetSuffixToId, resolved.actor, { edit: opts.editBy, review: opts.reviewBy }, { executor: opts.executorBy, reporter: opts.reporterBy }, resolved.actor, dryRun, true, // skipClaim: the task is already "doing" and remains claimed
440
497
  worktreeBase, planGenPaths, execDefaults, undefined, {
441
- stage: snapshot.tasks[taskId]?.meta?.pipeline_stage === "reporter"
442
- ? "reporter"
443
- : snapshot.tasks[taskId]?.meta?.pipeline_stage === "executor"
444
- ? "executor"
445
- : undefined,
446
- stateRef: typeof snapshot.tasks[taskId]?.meta?.pipeline_state_ref === "string"
447
- ? snapshot.tasks[taskId]?.meta?.pipeline_state_ref
448
- : undefined,
498
+ stage: executorResume
499
+ ? "executor"
500
+ : snapshot.tasks[taskId]?.meta?.pipeline_stage === "reporter"
501
+ ? "reporter"
502
+ : snapshot.tasks[taskId]?.meta?.pipeline_stage === "executor"
503
+ ? "executor"
504
+ : undefined,
505
+ stateRef: executorResume?.stateRef ??
506
+ (typeof snapshot.tasks[taskId]?.meta?.pipeline_state_ref === "string"
507
+ ? snapshot.tasks[taskId]?.meta?.pipeline_state_ref
508
+ : undefined),
509
+ ...(executorResume
510
+ ? { executorTarget: executorResume, worktree: executorWorktree }
511
+ : {}),
449
512
  }, opts);
450
513
  if (typeof prepared !== "string") {
514
+ if (pendingExecutorUnblock) {
515
+ writeEventFile(schedulePath, pendingExecutorUnblock);
516
+ pendingExecutorUnblock = undefined;
517
+ }
451
518
  const attempts = snapshot.tasks[taskId]?.meta?.limit_attempts;
452
519
  prepared.priorLimitAttempts =
453
520
  typeof attempts === "string" && /^\d+$/.test(attempts)
@@ -496,6 +563,7 @@ export function registerResumeCommand(exec) {
496
563
  cmd.option("--project <projectId>", "Project id in .specdojo/specdojo.config.json");
497
564
  cmd.option("--task <taskId>", 'Resume only this task ("doing", blocked pipeline stage, or due with --due)');
498
565
  cmd.option("--due", "Atomically claim and resume only retryable limit blocks whose resume time has arrived", false);
566
+ cmd.option("--resume-from <stage>", "Restart at executor, preserving existing work (requires --task; cannot be combined with --due)");
499
567
  cmd.option("--by <nickname>", "Select an agent-members.yaml agent (default: the agent that claimed the task)");
500
568
  cmd.option("--edit-by <nickname>", "agent-members.yaml nickname for edit-mode tasks (overrides the claiming actor)");
501
569
  cmd.option("--review-by <nickname>", "agent-members.yaml nickname for review-mode tasks (overrides the claiming actor)");
@@ -511,6 +579,7 @@ export function registerResumeCommand(exec) {
511
579
  cmd.option("--dry-run", "Print resolved commands without executing", false);
512
580
  cmd.action(async (opts) => {
513
581
  try {
582
+ validateScheduleResumeOptions(opts);
514
583
  if (opts.by && opts.executorBy) {
515
584
  process.stdout.write("Specify either --by or --executor-by, not both.\n");
516
585
  process.exitCode = 1;
@@ -1,3 +1,4 @@
1
+ import { parseProductBranchOverrides } from "../product-branches.js";
1
2
  import { loadExecDefaultsConfig, resolveRegisterPostReview } from "../agent-config.js";
2
3
  import { resolveProjectPaths } from "../project.js";
3
4
  import { isRegisterFailureMode } from "../register.js";
@@ -16,6 +17,7 @@ export function registerRunCommand(exec) {
16
17
  rcmd.option("--project <projectId>", "Project id in .specdojo/specdojo.config.json");
17
18
  rcmd.option("--by <nickname>", "Select an agent-members.yaml agent for a manual target");
18
19
  rcmd.option("--auto", "Automatically select and run next ready task", false);
20
+ rcmd.option("--track <track>", "Limit --auto selection to one schedule track");
19
21
  rcmd.option("--task <taskId>", "Task ID to run (manual selection)");
20
22
  rcmd.option("--deliverable <localId>", "Catalog deliverable local_id target (unique project-wide)");
21
23
  rcmd.option("--plan <path>", "Run an existing plan file (in-place; no generation)");
@@ -40,6 +42,7 @@ export function registerRunCommand(exec) {
40
42
  rcmd.option("--track-state", "Record claim/complete events (requires --task; --by optional, actor auto-derived from the resolved agent)", false);
41
43
  rcmd.option("--archive-on-success", "Archive the generated plan to exec/plans/done/ after a successful in-place run", false);
42
44
  rcmd.option("--integration-branch <repo=branch>", "With register worktree mode: integrate the declared product repository <repo> into the local branch <branch> for this run (repeatable; overrides repos[].integration_branch; resume reuses the value recorded at the start)", (value, previous = []) => [...previous, value]);
45
+ rcmd.option("--branch <repo=name>", "With register worktree mode: override a declared product work branch (repeatable; resume keeps the recorded branch)", (value, previous = []) => [...previous, value]);
43
46
  rcmd.option("--parallel <n>", "Number of worktree instances to run in parallel", "1");
44
47
  rcmd.option("--worktree-base <path>", "Override worktree base directory");
45
48
  rcmd.option("--strategy <s>", "Task selection strategy: critical-first|fifo (default: critical-first)");
@@ -69,6 +72,11 @@ export function registerRunCommand(exec) {
69
72
  const hasJob = !!opts.job;
70
73
  const isManual = hasTask || hasDeliverable || hasPlan || hasRegister || hasJob;
71
74
  const isBatch = isAuto;
75
+ if (opts.track !== undefined && !isAuto) {
76
+ process.stdout.write("--track requires --auto.\n");
77
+ process.exitCode = 1;
78
+ return;
79
+ }
72
80
  if (hasRegisterIds && hasRegisterFilter) {
73
81
  process.stdout.write("Specify either --register or --register-filter, not both.\n");
74
82
  process.exitCode = 1;
@@ -124,6 +132,20 @@ export function registerRunCommand(exec) {
124
132
  process.exitCode = 1;
125
133
  return;
126
134
  }
135
+ const branches = parseProductBranchOverrides(opts.branch);
136
+ if (branches.size > 0) {
137
+ if (!(hasRegister && opts.worktree)) {
138
+ process.stdout.write("--branch requires --register (or --register-filter) in worktree mode.\n");
139
+ process.exitCode = 1;
140
+ return;
141
+ }
142
+ const products = configuredProductRepos(resolveProjectPaths({ project: opts.project }).schedulePath);
143
+ for (const repo of branches.keys()) {
144
+ if (!products.some((product) => product.name === repo)) {
145
+ throw new Error(`--branch references undeclared product repository: ${repo}`);
146
+ }
147
+ }
148
+ }
127
149
  const integrationBranches = opts.integrationBranch ?? [];
128
150
  if (integrationBranches.length > 0) {
129
151
  if (!(hasRegister && opts.worktree)) {
@@ -1,3 +1,5 @@
1
+ import { loadConfig } from "../../shared/specdojo-config.js";
2
+ import { resolveProductBranches } from "../product-branches.js";
1
3
  import { registerDependencyBlockReason } from "../../register/dependency.js";
2
4
  import { existsSync, readFileSync } from "node:fs";
3
5
  import { resolve } from "node:path";
@@ -193,7 +195,15 @@ export async function resumeSingleRegisterItemWorktree(context, opts, pjrId, lif
193
195
  let integrationBranchOverrides;
194
196
  try {
195
197
  const overrides = resumeIntegrationBranches(target.state.integration_branches, opts.integrationBranch);
196
- products = configuredProductRepos(schedulePath, overrides);
198
+ products = resolveProductBranches(configuredProductRepos(schedulePath, overrides), {
199
+ projectId,
200
+ taskId: worktreeTaskId,
201
+ item,
202
+ ticketPath,
203
+ projectConfig: loadConfig().config?.projects[projectId],
204
+ overrides: opts.branch,
205
+ resume: true,
206
+ });
197
207
  integrationBranchOverrides = overrides.size > 0 ? Object.fromEntries(overrides) : undefined;
198
208
  }
199
209
  catch (error) {