specdojo 0.6.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 (60) hide show
  1. package/CHANGELOG.md +40 -0
  2. package/README.md +2 -2
  3. package/dist/commands/agent.js +33 -0
  4. package/dist/commands/init.js +1 -0
  5. package/dist/commands/orchestrator.js +10 -1
  6. package/dist/devcontainer/command.js +18 -0
  7. package/dist/devcontainer/host-script.js +21 -0
  8. package/dist/devcontainer/scaffold.js +4 -3
  9. package/dist/exec/antigravity-session.js +154 -0
  10. package/dist/exec/parent-validation.js +7 -0
  11. package/dist/exec/plan-markdownlint.js +89 -0
  12. package/dist/exec/plans-generation.js +6 -2
  13. package/dist/exec/register-resume.js +28 -0
  14. package/dist/exec/run/lifecycle-commands.js +85 -16
  15. package/dist/exec/run/register-command.js +6 -0
  16. package/dist/exec/run/schedule-mode.js +22 -2
  17. package/dist/exec/run/schedule-prepare.js +42 -1
  18. package/dist/exec/run/schedule-task.js +3 -0
  19. package/dist/exec/worktree-ops-commit.js +1 -13
  20. package/dist/exec/worktree-ops-lifecycle.js +40 -36
  21. package/dist/register/register.js +31 -23
  22. package/dist/shared/git.js +7 -0
  23. package/dist/shared/provider-scaffold.js +2 -0
  24. package/dist/shared/specdojo-gitignore.js +1 -0
  25. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +2 -0
  26. package/docs/ja/specdojo/guides/docs-editing-guide.md +36 -0
  27. package/docs/ja/specdojo/guides/exec-config-guide.md +14 -12
  28. package/docs/ja/specdojo/guides/exec-operation-guide.md +20 -8
  29. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +4 -2
  30. package/docs/ja/specdojo/guides/quick-start-guide.md +597 -871
  31. package/docs/ja/specdojo/guides/register-operation-guide.md +2 -0
  32. package/docs/ja/specdojo/guides/remote-host-development-guide.md +31 -4
  33. package/docs/ja/specdojo/guides/schedule-operation-guide.md +14 -0
  34. package/docs/ja/specdojo/guides/use-case-guide.md +537 -77
  35. package/docs/ja/specdojo/recipes/cdfd-overview-recipe.md +88 -86
  36. package/docs/ja/specdojo/recipes/cdfd-uc-recipe.md +96 -122
  37. package/docs/ja/specdojo/references/command-reference.md +69 -37
  38. package/docs/ja/specdojo/rulebooks/cdfd-d2-rulebook.md +367 -0
  39. package/docs/ja/specdojo/rulebooks/cdfd-mermaid-rulebook.md +6 -5
  40. package/docs/ja/specdojo/rulebooks/cdfd-overview-rulebook.md +96 -100
  41. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +38 -47
  42. package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +108 -103
  43. package/docs/ja/specdojo/samples/cdfd-overview-sample.md +248 -140
  44. package/docs/ja/specdojo/samples/cdfd-uc-sample.md +128 -97
  45. package/docs/ja/specdojo/templates/cdfd-overview-template.md +161 -83
  46. package/docs/ja/specdojo/templates/cdfd-uc-template.md +127 -90
  47. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +1 -0
  48. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +1 -0
  49. package/package.json +5 -2
  50. package/templates/antigravity/README.md +19 -46
  51. package/templates/antigravity/exec-defaults-snippet.yaml +5 -6
  52. package/templates/antigravity/settings.edit.json +73 -0
  53. package/templates/antigravity/settings.orchestrator.json +15 -0
  54. package/templates/antigravity/settings.report.json +7 -0
  55. package/templates/antigravity/settings.review.json +7 -0
  56. package/templates/devcontainer/remote-host/devcontainer-tmux.sh +217 -0
  57. package/templates/devcontainer/remote-host/specdojo-tmux.sh.sample +8 -96
  58. package/templates/devcontainer/remote-host/ssh-config.sample +3 -1
  59. package/templates/init-agent-members.yaml +1 -0
  60. package/templates/init-exec-defaults.yaml +1 -1
@@ -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;
@@ -17,6 +17,7 @@ export function registerRunCommand(exec) {
17
17
  rcmd.option("--project <projectId>", "Project id in .specdojo/specdojo.config.json");
18
18
  rcmd.option("--by <nickname>", "Select an agent-members.yaml agent for a manual target");
19
19
  rcmd.option("--auto", "Automatically select and run next ready task", false);
20
+ rcmd.option("--track <track>", "Limit --auto selection to one schedule track");
20
21
  rcmd.option("--task <taskId>", "Task ID to run (manual selection)");
21
22
  rcmd.option("--deliverable <localId>", "Catalog deliverable local_id target (unique project-wide)");
22
23
  rcmd.option("--plan <path>", "Run an existing plan file (in-place; no generation)");
@@ -71,6 +72,11 @@ export function registerRunCommand(exec) {
71
72
  const hasJob = !!opts.job;
72
73
  const isManual = hasTask || hasDeliverable || hasPlan || hasRegister || hasJob;
73
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
+ }
74
80
  if (hasRegisterIds && hasRegisterFilter) {
75
81
  process.stdout.write("Specify either --register or --register-filter, not both.\n");
76
82
  process.exitCode = 1;
@@ -5,6 +5,7 @@ import { activateResolvedProjectPaths, resolveProjectPaths } from "../project.js
5
5
  import { readAllEventFiles, foldEventsToState } from "../events.js";
6
6
  import { buildScheduleIndex, findStaleGeneratedTracks } from "../schedule/schedule.js";
7
7
  import { buildInitialStateFromStrategy } from "../schedule/initial.js";
8
+ import { scheduleTrackNames } from "../schedule/gantt-chart-scope.js";
8
9
  import { readReadySnapshot } from "../schedule/ready.js";
9
10
  import { specdojoRootDir } from "../../shared/specdojo-config.js";
10
11
  import { extractLocalId, extractPhaseSuffix } from "../../schedule/phase-sets.js";
@@ -52,6 +53,14 @@ export async function runBatchMode(opts) {
52
53
  const repoRoot = specdojoRootDir();
53
54
  const worktreeBase = resolveWorktreeBase(repoRoot, opts.worktreeBase, configuredWorktreeBase(schedulePath));
54
55
  const parallel = parseParallel(opts.parallel);
56
+ // Validate against the schedule, including tracks with no Ready tasks, before any claim.
57
+ const track = opts.track;
58
+ if (track !== undefined) {
59
+ const tracks = scheduleTrackNames(buildScheduleIndex(schedulePath));
60
+ if (!tracks.includes(track)) {
61
+ throw new Error(`Unknown schedule track: ${track}. Available tracks: ${tracks.join(", ")}`);
62
+ }
63
+ }
55
64
  const execDefaults = loadExecDefaultsConfig(resolveExecDefaultsPath(opts, schedulePath), executionPath);
56
65
  const roster = loadRosterForExecutionPath(executionPath);
57
66
  const { localIdToPhaseSets, phaseSetSuffixToId } = buildTaskPhaseMap(schedulePath);
@@ -67,12 +76,23 @@ export async function runBatchMode(opts) {
67
76
  return { preparedTasks: [], readyCount: 0 };
68
77
  }
69
78
  const readySnapshot = readReadySnapshot(readyJsonPath);
70
- const orderedIds = strategy === "fifo"
79
+ const strategyIds = strategy === "fifo"
71
80
  ? readySnapshot.strategies.fifo.ordered_task_ids
72
81
  : readySnapshot.strategies["critical-first"].ordered_task_ids;
82
+ const taskMap = new Map(readySnapshot.tasks.map((t) => [t.id, t]));
83
+ // Filter every snapshot before preparation, so setup failures and loop refills cannot
84
+ // escape the requested track. Use schedule_file rather than parsing hyphenated task IDs.
85
+ const orderedIds = track === undefined
86
+ ? strategyIds
87
+ : strategyIds.filter((id) => {
88
+ const task = taskMap.get(id);
89
+ if (!task)
90
+ return false;
91
+ const file = basename(task.schedule_file);
92
+ return file === `sch-track-${track}.yaml` || file === `sch-track-${track}.yml`;
93
+ });
73
94
  if (orderedIds.length === 0)
74
95
  return { preparedTasks: [], readyCount: 0 };
75
- const taskMap = new Map(readySnapshot.tasks.map((t) => [t.id, t]));
76
96
  const preparedTasks = [];
77
97
  for (const taskId of orderedIds) {
78
98
  if (preparedTasks.length >= limit)
@@ -1,3 +1,4 @@
1
+ import { existsSync } from "node:fs";
1
2
  import { join } from "node:path";
2
3
  import { resolveMemberCommand } from "../agent-config.js";
3
4
  import { canCompleteTask, readAllEventFiles, foldEventsToState } from "../events.js";
@@ -13,7 +14,7 @@ import { configuredProductRepos, plannedProjectWorktreePath, preflightProductBra
13
14
  import { checkpointAndEnsureWorktree, discardStaleExecWorktree } from "../worktree-ops.js";
14
15
  import { pipelineStateLocation } from "../pipeline-state.js";
15
16
  import { collectBusyActors, pinnedExecutor, pinnedReporter, resolveAgentOverride, resolveExecDefaultsPath, resolvePinnedRateLimitRunOptions, resolveTaskPhaseContext, selectCandidates, } from "./shared.js";
16
- import { buildExecutorPrompt, executorRequirements, loadPrompt, reportProductWorktrees, reporterRequirements, resolveReporterAgentCandidates, } from "./agent.js";
17
+ import { buildExecutorPrompt, executorRequirements, loadPrompt, pathInsideWorktree, reportProductWorktrees, reporterRequirements, resolveReporterAgentCandidates, } from "./agent.js";
17
18
  import { integrateLogPath, spawnClaim, spawnRelease } from "./mode-shared.js";
18
19
  export function findClaimEventPath(schedulePath, taskId) {
19
20
  const claims = readAllEventFiles(schedulePath).filter((item) => item.event.task_id === taskId && item.event.type === "claim");
@@ -162,6 +163,46 @@ export async function prepareSingleTask(task, projectId, repoRoot, schedulePath,
162
163
  const reporterRateLimitOptions = reporterPinned && reporterCandidates?.[0]
163
164
  ? resolvePinnedRateLimitRunOptions(rateLimitOverrides, execDefaults, roster, "reporter", reporterCandidates[0])
164
165
  : undefined;
166
+ if (pipelineResume?.executorTarget) {
167
+ const { executorTarget, worktree } = pipelineResume;
168
+ if (!worktree)
169
+ throw new Error(`no exec worktree to resume executor for ${task.id}`);
170
+ const worktreeExecutionPath = pathInsideWorktree(repoRoot, worktree.path, executionPath);
171
+ const planPrompt = loadPrompt(worktreeExecutionPath, task.id);
172
+ const resultPath = join(executionPath, "exec", "results", `${task.id}-result.md`);
173
+ const worktreeResultPath = pathInsideWorktree(repoRoot, worktree.path, resultPath);
174
+ if (!planPrompt || !existsSync(resultPath) || !existsSync(worktreeResultPath)) {
175
+ throw new Error(`plan or result is missing for executor resume: ${task.id}`);
176
+ }
177
+ const claimEventPath = findClaimEventPath(schedulePath, task.id);
178
+ if (!claimEventPath)
179
+ throw new Error(`claim event is missing for executor resume: ${task.id}`);
180
+ reportProductWorktrees(worktree);
181
+ return {
182
+ task,
183
+ actor,
184
+ agentCandidates,
185
+ plan: planPrompt,
186
+ prompt: buildExecutorPrompt(planPrompt, execDefaults.pipeline?.parent_validations),
187
+ worktree,
188
+ resultPath,
189
+ resultScaffold: readResultFrontmatterSnapshot(resultPath),
190
+ checkpointPaths: [
191
+ join(executionPath, "exec", "plans", `${task.id}-plan.md`),
192
+ resultPath,
193
+ claimEventPath,
194
+ ...gradeCheckpointPaths({ repoRoot, executionPath }),
195
+ ],
196
+ pipelineRunId: executorTarget.runId,
197
+ pipelineResumeStage: "executor",
198
+ pipelineStateRef: executorTarget.stateRef,
199
+ initialChangeTargets: executorTarget.initialChanges,
200
+ resumeHandoff: executorTarget.handoff,
201
+ reporterCandidates,
202
+ executorRateLimitOptions,
203
+ reporterRateLimitOptions,
204
+ };
205
+ }
165
206
  const reviewGradeOutcome = await gradeBeforeReviewPlan({
166
207
  task,
167
208
  projectId,
@@ -140,6 +140,8 @@ export async function runPreparedTask(prepared, projectId, repoRoot, schedulePat
140
140
  ? buildExecutorPrompt(prepared.plan, execDefaults.pipeline?.parent_validations, {
141
141
  resumed: true,
142
142
  existingChanges: worktreeStatusPaths(prepared.worktree.path),
143
+ initialChangeTargets: prepared.initialChangeTargets,
144
+ resumeHandoff: prepared.resumeHandoff,
143
145
  })
144
146
  : prepared.prompt;
145
147
  const executorOutcome = await runWithRetry(prepared.agentCandidates, withProductRepoPrompt(executorPrompt, prepared.worktree.repos), execDefaults, prepared.worktree.path, agentEnvironment(repoRoot, prepared.worktree.path, schedulePath, executionPath, prepared.worktree.repos), worktreeResultPath, prepared.executorRateLimitOptions);
@@ -178,6 +180,7 @@ export async function runPreparedTask(prepared, projectId, repoRoot, schedulePat
178
180
  plan: prepared.plan,
179
181
  evidence: executorEvidence,
180
182
  evidencePath: executorEvidencePath,
183
+ initialChangeTargets: prepared.initialChangeTargets,
181
184
  })
182
185
  : undefined;
183
186
  if (result === "success" && coverageFailure) {
@@ -11,7 +11,7 @@ import { assertNoPendingProductChanges, productIntegrationTarget } from "./task-
11
11
  import { specdojoPackageRootDir } from "../shared/package-paths.js";
12
12
  import { DEFAULT_MARKDOWNLINT_CONFIG, hasMarkdownlintConfig, } from "../shared/markdownlint-config.js";
13
13
  import { repoRelative, stageCommitTargets, worktreeStatusPaths as statusPaths, } from "../shared/git.js";
14
- export { repoRelative, selectStageablePaths, stageCommitTargets, worktreeStatusPaths, } from "../shared/git.js";
14
+ export { repoRelative, selectStageablePaths, stageCommitTargets, unstageCommitTargets, worktreeStatusPaths, } from "../shared/git.js";
15
15
  import { appendGitFailureLog, appendGitResultFailureLog, formatGitResultFailure, gitEnvironment, gitOutput, gitResult, summarizeGitHookFailure, worktreeNameFromTaskId, } from "./worktree.js";
16
16
  const MAX_COMMIT_STABILIZATION_ATTEMPTS = 3;
17
17
  export function currentBranch(repoRoot) {
@@ -392,18 +392,6 @@ export function partitionCommitTargets(context, worktree, taskId) {
392
392
  export function commitTargetPaths(context, worktree, taskId) {
393
393
  return partitionCommitTargets(context, worktree, taskId).targets;
394
394
  }
395
- // `git add` の pathspec は作業ツリーと index だけを照合する。削除が既に index へ入っている
396
- // パスはそのどちらにも存在しないため、`-A` を付けても「pathspec did not match any files」で
397
- // fatal になる。このようなパスは追加で stage する内容が無いので、add の対象から除外する。
398
- // commit / commit --amend の pathspec は HEAD も照合するため、対象から外さずに削除を記録できる。
399
- // runner が stage した対象だけを index から戻す。利用者や別処理が stage 済みの無関係な
400
- // パスは保持し、commit / hook の失敗を後続の exec run へ持ち越さない。
401
- export function unstageCommitTargets(repoRoot, paths) {
402
- const unique = [...new Set(paths)];
403
- if (unique.length === 0)
404
- return;
405
- gitOutput(repoRoot, ["reset", "--quiet", "--", ...unique]);
406
- }
407
395
  // markdownlint-cli の終了コード。1 だけが記法違反を表し、それ以外は実行環境の問題である。
408
396
  const MARKDOWNLINT_EXIT_LINT_ERRORS = 1;
409
397
  // worktree または SpecDojo package の node_modules から markdownlint-cli を探す。
@@ -254,45 +254,49 @@ function checkpointAndEnsureProjectWorktree(params, repoDirName, ensureSiblingWo
254
254
  const worktree = ensureProjectWorktree();
255
255
  for (const path of paths)
256
256
  copyCheckpointPath(context.repoRoot, worktree.path, path);
257
- stageCommitTargets(worktree.path, paths);
258
- const checkpointArgs = ["diff", "--cached", "--quiet", "--", ...paths];
259
- const checkpoint = gitResult(worktree.path, checkpointArgs);
260
- assertCheckpointInspection(checkpointArgs, checkpoint, params.failureLogPath);
261
- if (checkpoint.status === 1) {
262
- const committed = gitResult(worktree.path, [
263
- "commit",
264
- "-m",
265
- params.commitMessage,
266
- "--",
267
- ...paths,
268
- ]);
269
- if (committed.status !== 0) {
270
- // A failing git hook (pre-commit / commit-msg) aborts the commit but leaves the staged
271
- // paths in the index. Unstage only this checkpoint so a hook or caller's unrelated staged
272
- // paths remain intact.
273
- unstageCommitTargets(worktree.path, paths);
274
- // hook(lefthook 等)の生出力には ANSI エスケープや制御文字が含まれうる。この detail は
275
- // register 経路で pjr-index の結論列・result の理由欄へ伝播するため、ここで除去して
276
- // 表示崩れを防ぐ(register 側の sanitize と二重だが、非 register の呼び出し元も守る)。
277
- const output = [committed.stdout, committed.stderr]
278
- .map((part) => typeof part === "string" ? stripTerminalControlSequences(part).trim() : "")
279
- .filter(Boolean)
280
- .join("\n");
281
- appendGitFailureLog(params.failureLogPath, [
282
- `=== ${new Date().toISOString()} git commit checkpoint ===`,
283
- `exit: ${committed.status ?? "unknown"}`,
284
- "--- stdout ---",
285
- typeof committed.stdout === "string" ? committed.stdout : "",
286
- "--- stderr ---",
287
- typeof committed.stderr === "string" ? committed.stderr : "",
288
- "",
257
+ try {
258
+ stageCommitTargets(worktree.path, paths);
259
+ const checkpointArgs = ["diff", "--cached", "--quiet", "--", ...paths];
260
+ const checkpoint = gitResult(worktree.path, checkpointArgs);
261
+ assertCheckpointInspection(checkpointArgs, checkpoint, params.failureLogPath);
262
+ if (checkpoint.status === 1) {
263
+ const committed = gitResult(worktree.path, [
264
+ "commit",
265
+ "-m",
266
+ params.commitMessage,
267
+ "--",
268
+ ...paths,
289
269
  ]);
290
- throw new Error(
291
- // register の短い block_reason にも step とエラーが残るよう、補足より先に要約を置く。
292
- `Checkpoint commit failed: ${summarizeGitHookFailure(output)} ` +
293
- `(${params.commitMessage}; staged changes rolled back; likely a failing git hook)`);
270
+ if (committed.status !== 0) {
271
+ // hook(lefthook 等)の生出力には ANSI エスケープや制御文字が含まれうる。この detail は
272
+ // register 経路で pjr-index の結論列・result の理由欄へ伝播するため、ここで除去して
273
+ // 表示崩れを防ぐ(register 側の sanitize と二重だが、非 register の呼び出し元も守る)。
274
+ const output = [committed.stdout, committed.stderr]
275
+ .map((part) => typeof part === "string" ? stripTerminalControlSequences(part).trim() : "")
276
+ .filter(Boolean)
277
+ .join("\n");
278
+ appendGitFailureLog(params.failureLogPath, [
279
+ `=== ${new Date().toISOString()} git commit checkpoint ===`,
280
+ `exit: ${committed.status ?? "unknown"}`,
281
+ "--- stdout ---",
282
+ typeof committed.stdout === "string" ? committed.stdout : "",
283
+ "--- stderr ---",
284
+ typeof committed.stderr === "string" ? committed.stderr : "",
285
+ "",
286
+ ]);
287
+ throw new Error(
288
+ // register の短い block_reason にも step とエラーが残るよう、補足より先に要約を置く。
289
+ `Checkpoint commit failed: ${summarizeGitHookFailure(output)} ` +
290
+ `(${params.commitMessage}; staged changes rolled back; likely a failing git hook)`);
291
+ }
294
292
  }
295
293
  }
294
+ catch (error) {
295
+ // stage 後の検査や hook が失敗しても、この checkpoint の対象だけを戻す。
296
+ // root の index と、hook が別途 stage した無関係なパスには触れない。
297
+ unstageCommitTargets(worktree.path, paths);
298
+ throw error;
299
+ }
296
300
  return worktree;
297
301
  }
298
302
  return ensureProjectWorktree();
@@ -1,7 +1,7 @@
1
1
  import { existsSync, readFileSync } from "node:fs";
2
2
  import { relative, sep } from "node:path";
3
3
  import { CrossProcessMutex } from "../shared/cross-process-lock.js";
4
- import { gitOutput, gitResult, repoRelative, stageCommitTargets, worktreeStatusPaths, } from "../shared/git.js";
4
+ import { gitOutput, gitResult, repoRelative, stageCommitTargets, unstageCommitTargets, worktreeStatusPaths, } from "../shared/git.js";
5
5
  import { inlineCodeAnglePlaceholders } from "../shared/text.js";
6
6
  import { atomicWriteFile, buildRegisterItemContent, derivedTopicNeedsWarning, generatePjrId, printDerivedTopicWarning, registerEventActor, REGISTER_TOPIC_RE, resolveRegisterPaths, slugify, validateFields, } from "./core.js";
7
7
  import { registerCreateCommands, registerUpdateCommand } from "./create-commands.js";
@@ -109,36 +109,44 @@ function commitRegisterMutation(repoRoot, paths, command, result, preexisting, m
109
109
  process.stdout.write(`No register changes to commit for ${result.id}.\n`);
110
110
  return;
111
111
  }
112
- stageCommitTargets(repoRoot, changed);
113
- const staged = gitResult(repoRoot, ["diff", "--cached", "--quiet", "--", ...changed]);
114
- if (staged.status === 0) {
115
- process.stdout.write(`No register changes to commit for ${result.id}.\n`);
116
- return;
117
- }
118
- if (staged.status !== 1)
119
- throw new Error("Failed to inspect staged register changes.");
120
- const commitMessage = message?.trim() || defaultRegisterCommitMessage(command, result);
121
- if (commitMessage === "")
122
- throw new Error("Register commit message must not be empty");
123
- gitOutput(repoRoot, ["commit", "-m", commitMessage, "--", ...changed]);
124
- for (let attempt = 0; attempt < REGISTER_COMMIT_STABILIZATION_ATTEMPTS; attempt++) {
112
+ try {
113
+ stageCommitTargets(repoRoot, changed);
114
+ const staged = gitResult(repoRoot, ["diff", "--cached", "--quiet", "--", ...changed]);
115
+ if (staged.status === 0) {
116
+ process.stdout.write(`No register changes to commit for ${result.id}.\n`);
117
+ return;
118
+ }
119
+ if (staged.status !== 1)
120
+ throw new Error("Failed to inspect staged register changes.");
121
+ const commitMessage = message?.trim() || defaultRegisterCommitMessage(command, result);
122
+ if (commitMessage === "")
123
+ throw new Error("Register commit message must not be empty");
124
+ // --only は初回・amend とも指定し、開始前からある staged 変更を混ぜない。
125
+ gitOutput(repoRoot, ["commit", "--only", "-m", commitMessage, "--", ...changed]);
126
+ for (let attempt = 0; attempt < REGISTER_COMMIT_STABILIZATION_ATTEMPTS; attempt++) {
127
+ const remaining = worktreeStatusPaths(repoRoot).filter((path) => changed.includes(path));
128
+ if (remaining.length === 0) {
129
+ const sha = gitOutput(repoRoot, ["rev-parse", "--short", "HEAD"]).trim();
130
+ process.stdout.write(`Committed: ${sha} (${result.id})\n`);
131
+ return;
132
+ }
133
+ stageCommitTargets(repoRoot, remaining);
134
+ gitOutput(repoRoot, ["commit", "--only", "--amend", "--no-edit", "--", ...remaining]);
135
+ }
125
136
  const remaining = worktreeStatusPaths(repoRoot).filter((path) => changed.includes(path));
126
137
  if (remaining.length === 0) {
127
138
  const sha = gitOutput(repoRoot, ["rev-parse", "--short", "HEAD"]).trim();
128
139
  process.stdout.write(`Committed: ${sha} (${result.id})\n`);
129
140
  return;
130
141
  }
131
- stageCommitTargets(repoRoot, remaining);
132
- gitOutput(repoRoot, ["commit", "--amend", "--no-edit", "--", ...remaining]);
142
+ throw new Error(`Register commit incomplete: target paths remained dirty after hook stabilization:\n` +
143
+ remaining.map((path) => ` ${path}`).join("\n"));
133
144
  }
134
- const remaining = worktreeStatusPaths(repoRoot).filter((path) => changed.includes(path));
135
- if (remaining.length === 0) {
136
- const sha = gitOutput(repoRoot, ["rev-parse", "--short", "HEAD"]).trim();
137
- process.stdout.write(`Committed: ${sha} (${result.id})\n`);
138
- return;
145
+ catch (error) {
146
+ // changed は開始前に clean だった対象だけ。本文を残して、自分の stage だけを戻す。
147
+ unstageCommitTargets(repoRoot, changed);
148
+ throw error;
139
149
  }
140
- throw new Error(`Register commit incomplete: target paths remained dirty after hook stabilization:\n` +
141
- remaining.map((path) => ` ${path}`).join("\n"));
142
150
  }
143
151
  async function runRegisterMutationInCurrentWorktree(command, opts, mutate, requireCleanRegister) {
144
152
  const paths = resolveRegisterPaths(opts);
@@ -345,3 +345,10 @@ export function stageCommitTargets(repoRoot, paths) {
345
345
  return;
346
346
  gitOutput(repoRoot, ["add", "-A", "--", ...stageable]);
347
347
  }
348
+ // 呼び出し元が stage した対象だけを戻し、作業ツリーと無関係な staged 変更は保持する。
349
+ export function unstageCommitTargets(repoRoot, paths) {
350
+ const unique = [...new Set(paths)];
351
+ if (unique.length === 0)
352
+ return;
353
+ gitOutput(repoRoot, ["reset", "--quiet", "--", ...unique]);
354
+ }
@@ -16,6 +16,8 @@ export const ORCHESTRATOR_NPM_SCRIPTS = {
16
16
  "orch:luna": 'specdojo orchestrator launch --provider codex -- -m gpt-6-luna "$(cat .specdojo/codex/orchestrator.md)"',
17
17
  },
18
18
  antigravity: {
19
+ "orch:argon": 'specdojo orchestrator launch --provider antigravity -- --add-dir "$(pwd)" --model gemini-4-argon-medium -i "$(cat .specdojo/antigravity/orchestrator.md)"',
20
+ "orch:argon:work": 'tools/worktree/open-agent-worktree.sh argon-work specdojo orchestrator launch --provider antigravity -- --add-dir . --model gemini-4-argon-medium -i "$(cat .specdojo/antigravity/orchestrator.md)"',
19
21
  "orch:flash": 'specdojo orchestrator launch --provider antigravity -- --add-dir "$(pwd)" --model gemini-3.8-flash-high -i "$(cat .specdojo/antigravity/orchestrator.md)"',
20
22
  },
21
23
  opencode: {
@@ -13,6 +13,7 @@ export const DEFAULT_GITIGNORE_PATTERNS = [
13
13
  "/.vitepress/dist/",
14
14
  "/.vitepress/cache/",
15
15
  "/.vitepress/mermaid/",
16
+ "/.vitepress/d2/",
16
17
  "/.vitepress/kata-staging/",
17
18
  ];
18
19
  // repo-root 相対の posix パスへ正規化する。リポジトリ外(絶対パス・`..`)や root 自身は
@@ -348,6 +348,7 @@ viewpoints:
348
348
  - specdojo:bps-rulebook
349
349
  - specdojo:br-rulebook
350
350
  - specdojo:ccd-mermaid-rulebook
351
+ - specdojo:cdfd-d2-rulebook
351
352
  - specdojo:cdfd-mermaid-rulebook
352
353
  - specdojo:cdfd-overview-rulebook
353
354
  - specdojo:cdfd-rulebook
@@ -564,6 +565,7 @@ viewpoints:
564
565
  - specdojo:bps-rulebook
565
566
  - specdojo:br-rulebook
566
567
  - specdojo:ccd-mermaid-rulebook
568
+ - specdojo:cdfd-d2-rulebook
567
569
  - specdojo:cdfd-mermaid-rulebook
568
570
  - specdojo:cdfd-rulebook
569
571
  - specdojo:cdfd-uc-rulebook
@@ -346,6 +346,7 @@ Mermaid SVG の生成だけを行う場合は `npx specdojo-docs-site mermaid .`
346
346
  /.vitepress/dist/
347
347
  /.vitepress/cache/
348
348
  /.vitepress/mermaid/
349
+ /.vitepress/d2/
349
350
  /.vitepress/kata-staging/
350
351
  ```
351
352
 
@@ -390,3 +391,38 @@ block
390
391
  - ローカル検索は登録簿一覧 `pjr-index` を入口にし、個票、状態別などの派生ビュー、管理ログ、実行記録を検索インデックスから除外します。個票本文を探す場合は `pjr-index` から対象個票へ移動します。
391
392
 
392
393
  ステージングの参照元、Mermaid SVG だけを生成するコマンドなど、package 固有の設定は `packages/docs-site/README.md` を参照してください。
394
+
395
+ ### 6.2. 図の道具を選ぶ
396
+
397
+ 図の目的と複雑さで道具を選びます。agent もこの基準に従って作成・修正してください。
398
+
399
+ | 道具 | 選ぶ目安 | 正本 |
400
+ | ------- | -------------------------------------------------------------------------------- | ------------------------------------ |
401
+ | Mermaid | 単純な図、状態遷移図、シーケンス図など。ノードと辺がそれぞれおおむね 20 程度まで | Markdown の `mermaid` コードブロック |
402
+ | D2 | ノード・辺が多い構成図、入れ子が多い図、Mermaid で配置が読みづらくなる図 | Markdown の `d2` コードブロック |
403
+ | draw.io | さらに複雑で、人が配置を決めたい図や発表用の図 | 圧縮しない `.drawio` |
404
+
405
+ 20 は切り替えの目安です。図を読む目的が分かれる場合は、道具の変更とともに図の分割も検討します。draw.io の自動書き出しは別途整備するため、現時点では表示用の SVG を手動で用意してください。
406
+
407
+ ### 6.3. D2 図を書く・検査する
408
+
409
+ `d2` のコードブロックは `build` と `dev` で SVG に書き出します。D2 CLI v0.9.0 を PATH に配置してください。このリポジトリの Dev Container はコンテナの再ビルドで導入されます。Linux で手動導入する場合は、版と SHA-256 を固定した `sh .devcontainer/install-d2.sh "$HOME/.local/bin"` を使えます。
410
+
411
+ ````markdown
412
+ ```d2
413
+ direction: right
414
+ client: 利用者
415
+ system: システム {
416
+ api: API
417
+ db: データベース {shape: cylinder}
418
+ api -> db: 読み書き
419
+ }
420
+ client -> system.api: リクエスト
421
+ ```
422
+ ````
423
+
424
+ 配置の既定は ELK です。図はコードブロック内で完結させ、外部ファイルの import は使いません。1 つのブロックにつきルートの図を 1 枚の SVG にします。layers・scenarios・steps の追加ページは書き出しません。生成 SVG は `.vitepress/d2/`、公開 URL はサイトの base に続く `/d2/<hash>.svg` です。SVG は生成物なので直接編集しません。
425
+
426
+ 生成だけを行う場合は `npx specdojo-docs-site d2 .` を使います。本リポジトリの構文検査は `node tools/lint-d2.mjs`、対象を絞る場合は `node tools/lint-d2.mjs '<Markdown のパスまたは glob>'` です。開始 fence の行番号とエラーを報告し、不正な図は終了コード 1 になります。D2 を含む文書がある場合、CLI が未導入・版違いでも失敗します。ブラウザは不要です。
427
+
428
+ GitHub の Markdown 表示では D2 は図に変換されないため、文書サイトで確認します。npm の `lint:d2`・`check`、commit hook とこのリポジトリの親検証設定への登録、および CI の導入設定は、保護された設定の承認・反映後に有効になります。