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
@@ -115,7 +115,9 @@ exec の result の commit 前検査は markdownlint-cli が読む利用リポ
115
115
  `.markdownlintrc` を含む)を優先し、設定がなければ上記の6規則だけをコマンド引数で無効にします。
116
116
  フォールバック用ファイルは利用リポジトリに作りません。CLI2 専用設定はこの検査では読みません。
117
117
 
118
- `package.json` がある場合、provider ごとのオーケストレーター起動スクリプトも追加します。Claude Code は `orch:opus`・`orch:sonnet`、Codex は `orch:sol`(`gpt-6.1-sol`)・`orch:luna`(`gpt-6-luna`)、Antigravity は `orch:flash`(`gemini-3.8-flash-high`)、OpenCode は `orch:opencode` です。既存のスクリプトは `--force` を付けても上書きしません。
118
+ `package.json` がある場合、provider ごとのオーケストレーター起動スクリプトも追加します。Claude Code は `orch:opus`・`orch:sonnet`、Codex は `orch:sol`(`gpt-6.1-sol`)・`orch:luna`(`gpt-6-luna`)、Antigravity は `orch:argon`(`gemini-4-argon-medium`)・`orch:flash`(`gemini-3.8-flash-high`)、OpenCode は `orch:opencode` です。既存のスクリプトは `--force` を付けても上書きしません。
119
+
120
+ agy 1.4.12 以降向けの通常導入は edit / review / report / orchestrator のセッション別プロファイルを配置し、ユーザー設定を書き換えません。非対話用 command template は `specdojo agent launch --provider antigravity --role {mode} -- --sandbox --model {model} -p "$(cat)"`、対話型は `specdojo orchestrator launch --provider antigravity -- <agy 引数>` を使います。各入口が宣言済みルートの保護ルールを一つの `--settings` JSON として渡します。`agent launch` は runner の `SPECDOJO_REPO_*` に示された task worktree と cwd だけを追加し、任意の `--add-dir` や別 `--settings`、bypass、既存会話の再開を拒否します。review / report は全書き込み・command・MCP を拒否します。詳しい移行と実機確認は [[sysd-antigravity-agent-settings|Antigravity CLI エージェント設定]] を参照してください。
119
121
 
120
122
  `antigravity` に限り `--global` を指定すると、`~/.gemini/antigravity-cli/settings.json` へ SpecDojo 用の permission rule を追記します。既存キー・既存 rule は保持し、実書き込み前に timestamp 付きバックアップを作ります。`--global` を省略した通常実行はユーザーディレクトリへ触れません。適用前は次の dry-run で追加 rule を確認してください。
121
123
 
@@ -296,16 +298,19 @@ specdojo config scaffold --workspace --force
296
298
 
297
299
  主要オプション:
298
300
 
299
- | オプション | 用途 |
300
- | -------------------- | ------------------------------------------------------------------------- |
301
- | `--size <size>` | `small` / `medium` / `large` の成果物セットを選ぶ |
302
- | `--project-id <id>` | 生成ファイルに埋め込む project ID を上書きする |
303
- | `--domain <domain>` | `catalog scaffold` の対象をtemplateの`domain`で絞る(反復・カンマ区切り) |
304
- | `--var <NAME=value>` | `catalog scaffold` で`_NAME_` placeholderを置換する(反復可能) |
305
- | `--plan` | 保存済みの `dct-plan-<domain>.yaml` から決定論的に生成する |
306
- | `--dry-run` | `--plan` の生成結果と既存ファイルとの差分を、書き込まずに表示する |
307
- | `--dct <name>` | `deliverable scaffold` の対象を特定の `dct-*.yaml` に絞る(後述) |
308
- | `--force` | 既存ファイルを上書きする |
301
+ | オプション | 用途 |
302
+ | ------------------------------ | ---------------------------------------------------------------------------------- |
303
+ | `--size <size>` | `small` / `medium` / `large` の成果物セットを選ぶ |
304
+ | `--project-id <id>` | 生成ファイルに埋め込む project ID を上書きする |
305
+ | `--domain <domain>` | `catalog scaffold` の対象をtemplateの`domain`で絞る(反復・カンマ区切り) |
306
+ | `--var <NAME=value>` | `catalog scaffold` で`_NAME_` placeholderを置換する(反復可能) |
307
+ | `--plan` | 保存済みの `dct-plan-<domain>.yaml` から決定論的に生成する |
308
+ | `--dry-run` | `--plan` の生成結果と既存ファイルとの差分を、書き込まずに表示する |
309
+ | `--dct <name>` | `deliverable scaffold` の対象を特定の `dct-*.yaml` に絞る(後述) |
310
+ | `--target <doc-id>` | `deliverable scaffold` で特定の成果物 1 件だけを雛形にする(`--dct` との併用不可) |
311
+ | `--target-path <path>` | カタログにない成果物の配置パス(`--target` と `--target-rulebook` と併用) |
312
+ | `--target-rulebook <rulebook>` | カタログにない成果物の rulebook 文書 ID(`--target` と `--target-path` と併用) |
313
+ | `--force` | 既存ファイルを上書きする |
309
314
 
310
315
  `catalog scaffold`は、`--domain`を省略すると従来どおりすべてのDCT templateを対象にします。指定した場合は、ファイル名ではなくtemplate内の`domain`が一致するものだけを生成します。存在しないdomainを指定した場合は、部分的な生成を行わずエラーで終了します。
311
316
 
@@ -330,6 +335,22 @@ specdojo deliverable scaffold --project prj-0001 --dct project-definition
330
335
  specdojo deliverable scaffold --project prj-0001 --dct dct-project-definition.yaml,dct-project-management.yaml
331
336
  ```
332
337
 
338
+ `--target <doc-id>` で成果物を 1 件だけ指定して雛形を作成できます(`--dct` とは併用できません)。カタログに登録されている成果物は、カタログの配置・rulebook・template の情報から 1 件だけ雛形を生成します。
339
+
340
+ カタログにない成果物は `--target-path <path>` と `--target-rulebook <rulebook>` をあわせて指定することで雛形を作成できます。パスの検証(リポジトリの中か、ファイル名か、ほかの文書が使っていないか)は register の `--target-path` と同じ規則で行われます。
341
+
342
+ `--dry-run` を指定するとファイルへの書き込みを行わず、作成予定(`Would create: <path>`)のみを表示します。既存ファイルがある場合は、`--force` が指定されていない限りスキップされます。
343
+
344
+ ```bash
345
+ # カタログにある成果物を 1 件だけ雛形にする
346
+ specdojo deliverable scaffold --project prj-0001 --target prj-charter
347
+
348
+ # カタログにない成果物を雛形にする
349
+ specdojo deliverable scaffold --project prj-0001 --target my-spec \
350
+ --target-path docs/ja/product/my-spec.md \
351
+ --target-rulebook specdojo:cdfd-rulebook
352
+ ```
353
+
333
354
  `deliverable scaffold` の生成方針と `specdojo build` に含めない理由は [遂行の技活用ガイド](../guides/waza-guide.md) の `deliverable scaffold の生成方針`、生成系動詞の使い分けは同ガイドの `生成系動詞の標準`、成果物カタログから Schedule への展開は [Schedule設計ガイド](../guides/schedule-design-guide.md) の `成果物カタログとの責務分担` を参照します。
334
355
 
335
356
  ### 3.1. catalog plan(成果物インスタンスの判定)
@@ -489,6 +510,7 @@ specdojo schedule strategy generate \
489
510
 
490
511
  | オプション | 用途 | 対象 |
491
512
  | ---------------------------- | ------------------------------------------------------------------- | ------------------------------------------------ |
513
+ | `--input <text>` | 個票の前提を記録(繰り返し可、update は一覧置換、`-` 単独で全削除) | `add` / `update` |
492
514
  | `--track <track>` | epic が担う track(epic で必須、update で置換、削除不可) | `add` / `update` |
493
515
  | `--to <PJR-ID>` | 移動先の PJR-ID を指定する | `renumber` |
494
516
  | `--registered <datetime>` | 起票日時(タイムゾーン付き RFC 3339)。省略時は実行時刻 | `add` |
@@ -502,6 +524,8 @@ specdojo schedule strategy generate \
502
524
  | `--target-path <path>` | 成果物のリポジトリ相対パス(`update` は `-` で削除) | `add` / `update` |
503
525
  | `--target-rulebook <doc-id>` | 成果物の rulebook ID(`update` は `-` で削除) | `add` / `update` |
504
526
  | `--source <ref>` | kata authoring の手本を指定(繰り返し可、`update` では `-` で削除) | `add` / `update` |
527
+ | `--commit-type <type>` | Conventional Commits の type を指定(`update` は `-` で削除) | `add` / `update` |
528
+ | `--commit-scope <scope>` | Conventional Commits の scope を指定(`update` は `-` で削除) | `add` / `update` |
505
529
  | `--topic <slug>` | 個票ファイル名と文書 ID の論点部分を指定・更新する | `add` / `update` |
506
530
  | `--commit` | `register lifecycle` 枠内で記帳・再生成・commitを行う | `add` / `update` / `renumber` / 遷移 |
507
531
  | `-m, --message <message>` | `--commit` のcommitメッセージを上書きする | `add` / `update` / `renumber` / 遷移 |
@@ -517,6 +541,12 @@ specdojo schedule strategy generate \
517
541
 
518
542
  `register` の `--by` は、project の `pm-members.yaml` にある人の nickname、`.specdojo/agent-members.yaml` にある agent の nickname または alias、予約 actor の `SpecDojo`・`specdojo-orchestrator`・`night-orchestrator` だけを受け付けます。agent alias は実体名で event に記録し、未知の値は書き込み前に拒否します。省略時は `SpecDojo` です。決定・承認では `PO` などの Role code や予約 actor ではなく、本人の nickname を指定します。
519
543
 
544
+ `--input <text>` は、対話で得た前提・制約・委任範囲を個票本文の `入力` 節へ指定順に記録します。`update` で未指定なら保持し、指定すれば一覧を置換します。追記するときは既存分も含めて再指定し、`--input -` 単独で全削除します。add での `-`、空文字、削除と他の値の混在は拒否します。既存個票に節がなければ更新時に追加します。event の `input` は変更前後の JSON 配列を保持し、空は `-` で表します。register から生成する plan は approach の有無によらず、入力がある場合だけ完了条件とは別の「個票の入力(前提)」へ載せます。
545
+
546
+ `--commit-type <type>` と `--commit-scope <scope>` は、個票 Frontmatter の `commit_type` と `commit_scope` に Conventional Commits の type と scope を記録します。`update` では未指定なら保持し、`-` で削除します。`commit_type` に指定できる値は Conventional Commits の type(`feat`・`fix`・`docs`・`refactor`・`test`・`chore`・`perf`・`build`・`ci`・`style`・`revert`)です。`commit_scope` は英小文字・数字・ハイフン(`^[a-z0-9][a-z0-9-]*$`)を指定します。個票で `commit_type` を指定しなかった場合は、項目の type から既定の対応(`issue` は `fix`、`todo`・`change-request` は `feat`、`decision`・`note`・`question`・`risk` は `docs`、`epic` は `feat`、未知の type は `chore`)またはプロジェクト・リポジトリの設定により決定されます。
547
+
548
+ 既定値は個票へ書き込まず、共通関数で利用時に解決します。優先順位と設定例は [[specdojo:specdojo-config-reference|設定リファレンス]] を参照してください。この段階では exec の commit メッセージやブランチ名には反映しません。
549
+
520
550
  `--approach` を指定する場合、通常は `--target` が 1 件だけ必須です。成果物を作成・修正する approach の対象は、成果物カタログを優先して doc id を解決します。カタログがなくても、既存文書は文書索引と frontmatter から、新規文書は明示したパスと rulebook から解決できます。kata maintenance の対象は文書索引で解決し、approach に対応する kata 種別との一致も書き込み前に検証します。kata authoring は `--target` を新しい kata ID、`--source` を 0 件以上の読み取り専用の手本とします。互換性のため、2 個目以降の `--target` も `--source` と同じ手本として扱います。
521
551
 
522
552
  `sample-maintenance` は `type` を見ず、対象 `id` の末尾が `-sample` かどうかで判定します。利用者の authority の sample も同じ規則です。recipe・template・rulebook の maintenance は従来どおり `type` の一致を検証します。sample の `type` の規約は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] を参照してください。
@@ -617,6 +647,8 @@ kata authoring は register 専用です。Schedule の task は対象成果物
617
647
  | `exec plan` | plan だけを生成する | `specdojo exec plan --project prj-0001 --task <task-id>` |
618
648
  | `exec archive` | 完了済み plan を `done/` へ移動する | `specdojo exec archive --project prj-0001 --task <task-id>` |
619
649
 
650
+ schedule の `exec resume --task <task-id> --resume-from executor` は、executor が `succeeded` で reporter が未完了の pipeline を、既存 worktree・変更・同じ run を引き継いで executor → reporter → 統合の順に再実行します。対象状態は reporter 段の `blocked` または中断した `doing` で、executor の試行回数を増やし、`blocked` からの状態遷移は `unblock` イベントへ記録します。統合段、executor 未成功、pipeline 以外、`executor` 以外の値は拒否します。`--task` は必須で、`--due` とは併用できません。worktree の `<execution_path>/exec/plans/<task-id>-plan.md` を編集してから再開すると、その plan を使います。変更理由と再開の経緯を報告の `handoff` へ記載するよう plan に指示し、再開後の result の申し送りを確認してください。手順は [[specdojo:exec-operation-guide|exec運用ガイド]] の「blockedタスクの復帰」を参照してください。
651
+
620
652
  `exec scaffold --project <project-id>` は、対象 project の `viewpoints_path` へ `extends: specdojo:pm-review-viewpoints` を持つ空の差分ファイルを生成します。共通正本は [[specdojo:pm-review-viewpoints|共通レビュー観点一覧]] であり、scaffold 時点の全量コピーは作りません。そのため、共通側の更新は次回の review plan 生成時に継承 project へ反映されます。既存ファイルは既定で保持し、`--force` の指定時だけ差分雛形で置き換えます。
621
653
 
622
654
  プロジェクト差分の upsert、無効化、独自ロールの宣言規則は [[specdojo:review-guide|レビューガイド]] を参照してください。provider 設定の推奨入口は `config scaffold --provider <name>` です。従来の `exec scaffold --provider <name>` も互換入口として同じ設定一式を生成します。
@@ -630,34 +662,36 @@ kata authoring は register 専用です。Schedule の task は対象成果物
630
662
 
631
663
  主要オプション:
632
664
 
633
- | オプション | 用途 | 対象 |
634
- | -------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
635
- | `--task <task-id>` | 対象タスクを指定する | 状態遷移系 / `run` / `plan` |
636
- | `--by <actor>` | 実行 actor / agent の nickname を指定する(手動ターゲットの agent 選択も兼ねる) | 状態遷移系 / `run` / `resume` / `worktree agent` |
637
- | `--edit-by <nickname>` | `--auto` バッチで edit タスクに使う agent nickname | `run --auto` / `resume` |
638
- | `--review-by <nickname>` | `--auto` の review タスク、または register の統合後 review に使う agent nickname | `run --auto` / `run --register --post-review` / `resume` |
639
- | `--strategy <name>` | 選択戦略を切り替える(`critical-first` 既定 / `fifo`) | `scheduler` / `run --auto` |
640
- | `--auto` / `--loop` | Ready タスクを自動選択する / Ready がなくなるまで繰り返す | `run` |
641
- | `--parallel <n>` | 同時に走らせる agent 数の上限を指定する | `run --auto` / register の worktree モード |
642
- | `--worktree` | worktree に隔離して実行する | `run --task` / `run --register` |
643
- | `--in-place` | register 項目を現在の作業ツリーで実行する(`run.register_execution` を上書き) | `run --register` |
644
- | `--track-state` | claim / complete の状態イベントを記録する | `run --task` |
645
- | `--register <PJR-ID>` | 登録簿の項目を実行する(空白・カンマ区切りで複数可。場所の既定は `run.register_execution`) | `run` / `plan` |
646
- | `--register-filter` | 登録簿項目を type / priority / status / limit の条件で決定論的に選ぶ | `run` |
647
- | `--register-commit` | 成功したIDごとに、その実行で生じた変更を1コミットにまとめる(worktree モードでは常に commit のため無視) | `run --register` |
648
- | `--post-review` | worktree 統合後に完了 review を行い、todo / issue を verdict に応じて close または waiting にする | `run --register --worktree` |
649
- | `--on-failure <stop\|continue>` | 途中失敗時に残りのIDを停止するか継続するか(既定は `stop`) | `run --register` |
650
- | `--integration-branch <repo>=<branch>` | run ごとのプロダクトリポジトリの統合先(繰り返し可)を指定する | register の worktree モード |
651
- | `--resume` | run が止まった段(executor / reporter / 統合)を既存 worktree と checkpoint で再開する | register の worktree モード |
652
- | `--resume-from executor` | reporter 段から再開可能な run を、既存成果を保持したまま executor 段から再開する | register の worktree モード(`--resume` と併用) |
653
- | `--force-restart` | 再開可能な run の成果があっても、worktree を破棄して項目全体を再実行する | register の worktree モード |
654
- | `--join` | 実行中の register worktree 実行の終了を待たずに合流して並行実行する(上限は `run.max_concurrent_runs`) | register の worktree モード |
655
- | `--executor-by <nickname>` | executor 段の agent。register では `PJR-ID=nickname,...` による項目別指定も可能 | `run --auto` / `resume` / `run --register` / `run --plan` / `run --deliverable` |
656
- | `--reporter-by <nickname>` | executor/reporter パイプラインの reporter 段に使う agent nickname | `run --auto` / `resume` / `run --register` / `run --plan` / `run --deliverable` |
657
- | `--on-rate-limit <action>` | 指名した agent の上限時の扱い。`stop` / `wait` / `fallback` | `run` / `resume` |
658
- | `--fallback-executor-by <name>` | rate limit の `fallback` または接続不能時に executor 段を1回だけ引き継ぐ agent | `run` / `resume` |
659
- | `--fallback-reporter-by <name>` | rate limit の `fallback` または接続不能時に reporter 段を1回だけ引き継ぐ agent | `run` / `resume` |
660
- | `--due` | 再開時刻を迎えた利用制限延期 task を対象にする | `resume` |
665
+ | オプション | 用途 | 対象 |
666
+ | -------------------------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
667
+ | `--task <task-id>` | 対象タスクを指定する | 状態遷移系 / `run` / `plan` |
668
+ | `--by <actor>` | 実行 actor / agent の nickname を指定する(手動ターゲットの agent 選択も兼ねる) | 状態遷移系 / `run` / `resume` / `worktree agent` |
669
+ | `--edit-by <nickname>` | `--auto` バッチで edit タスクに使う agent nickname | `run --auto` / `resume` |
670
+ | `--review-by <nickname>` | `--auto` の review タスク、または register の統合後 review に使う agent nickname | `run --auto` / `run --register --post-review` / `resume` |
671
+ | `--strategy <name>` | 選択戦略を切り替える(`critical-first` 既定 / `fifo`) | `scheduler` / `run --auto` |
672
+ | `--auto` / `--loop` | Ready タスクを自動選択する / Ready がなくなるまで繰り返す | `run` |
673
+ | `--track <track>` | `--auto` の選択を 1 つの track に限定する。存在しない track は claim 前にエラー。省略時は全 track が対象 | `run --auto`(`--parallel` / `--loop` / `--dry-run` と併用可能) |
674
+ | `--parallel <n>` | 同時に走らせる agent 数の上限を指定する | `run --auto` / register の worktree モード |
675
+ | `--worktree` | worktree に隔離して実行する | `run --task` / `run --register` |
676
+ | `--in-place` | register 項目を現在の作業ツリーで実行する(`run.register_execution` を上書き) | `run --register` |
677
+ | `--track-state` | claim / complete の状態イベントを記録する | `run --task` |
678
+ | `--register <PJR-ID>` | 登録簿の項目を実行する(空白・カンマ区切りで複数可。場所の既定は `run.register_execution`) | `run` / `plan` |
679
+ | `--register-filter` | 登録簿項目を type / priority / status / limit の条件で決定論的に選ぶ | `run` |
680
+ | `--register-commit` | 成功したIDごとに、その実行で生じた変更を1コミットにまとめる(worktree モードでは常に commit のため無視) | `run --register` |
681
+ | `--post-review` | worktree 統合後に完了 review を行い、todo / issue を verdict に応じて close または waiting にする | `run --register --worktree` |
682
+ | `--on-failure <stop\|continue>` | 途中失敗時に残りのIDを停止するか継続するか(既定は `stop`) | `run --register` |
683
+ | `--branch <repo>=<name>` | run ごとのプロダクト作業ブランチ名(繰り返し可)を指定する | register の worktree モード |
684
+ | `--integration-branch <repo>=<branch>` | run ごとのプロダクトリポジトリの統合先(繰り返し可)を指定する | register の worktree モード |
685
+ | `--resume` | run が止まった段(executor / reporter / 統合)を既存 worktree と checkpoint で再開する | register の worktree モード |
686
+ | `--resume-from executor` | reporter 段から再開可能な run を、既存成果を保持したまま executor 段から再開する | register の worktree モード(`--resume` と併用)、schedule の `resume --task`(`--due` と併用不可) |
687
+ | `--force-restart` | 再開可能な run の成果があっても、worktree を破棄して項目全体を再実行する | register の worktree モード |
688
+ | `--join` | 実行中の register worktree 実行の終了を待たずに合流して並行実行する(上限は `run.max_concurrent_runs`) | register の worktree モード |
689
+ | `--executor-by <nickname>` | executor 段の agent。register では `PJR-ID=nickname,...` による項目別指定も可能 | `run --auto` / `resume` / `run --register` / `run --plan` / `run --deliverable` |
690
+ | `--reporter-by <nickname>` | executor/reporter パイプラインの reporter 段に使う agent nickname | `run --auto` / `resume` / `run --register` / `run --plan` / `run --deliverable` |
691
+ | `--on-rate-limit <action>` | 指名した agent の上限時の扱い。`stop` / `wait` / `fallback` | `run` / `resume` |
692
+ | `--fallback-executor-by <name>` | rate limit の `fallback` または接続不能時に executor 段を1回だけ引き継ぐ agent | `run` / `resume` |
693
+ | `--fallback-reporter-by <name>` | rate limit の `fallback` または接続不能時に reporter 段を1回だけ引き継ぐ agent | `run` / `resume` |
694
+ | `--due` | 再開時刻を迎えた利用制限延期 task を対象にする | `resume` |
661
695
 
662
696
  `--plan` と `--deliverable` も Schedule のパイプライン宣言を持たないため、`--executor-by` / `--reporter-by` の少なくとも一方を指定したときだけ executor/reporter 2段階で実行します。指定しなかった段は `stage_role` による自動選択で決まります。`--plan` では reporter が scaffold 済みの result を記入するため、frontmatter に `task_id` を持つ plan が必要です。`--by` との併用はエラーです。`--by` に `stage_role` を持つ pipeline 用 agent を指定すると、result 未記入の blocked にはせず、`--executor-by` / `--reporter-by` を使うよう案内するエラーで実行前に拒否します。
663
697
 
@@ -689,6 +723,9 @@ specdojo exec run --project prj-0001 --auto --parallel 5
689
723
  # Ready がなくなるまで連続実行する
690
724
  specdojo exec run --project prj-0001 --auto --loop --parallel 5
691
725
 
726
+ # 指定した track だけを連続実行する
727
+ specdojo exec run --project prj-0001 --auto --track data-flow-uc-rewrite --loop --parallel 3
728
+
692
729
  # 登録簿の項目を実行する(開始で in-progress、成功で review、失敗で waiting へ遷移)
693
730
  specdojo exec run --project prj-0001 --register PJR-0012
694
731
 
@@ -734,6 +771,10 @@ specdojo exec run --project prj-0001 --job job-weekly-report --input period=2026
734
771
 
735
772
  `--register` は指定した個票の項目を実行します。`--register-filter` は `--register-types` / `--register-priorities` / `--register-statuses` のカンマ区切り条件と、正の整数の `--register-limit` で項目を選びます。条件省略時は open かつ実行可能な type が対象です。いずれも実行対象になる type は `todo` / `issue` / `change-request` / `question` / `risk` で、`epic` / `decision` / `note` は対象外です。実行場所の既定は `.specdojo/exec-defaults.yaml` の `run.register_execution`(`worktree` / `in-place`)で選び、未設定時は互換性のため in-place です。`--worktree` / `--in-place` は設定を上書きし、同時指定はエラーになります。worktree モードは成果物の変更を隔離し、状態遷移(`start` / `review` / `waiting`)を直列化したうえで、成功時に merge back します。`--post-review` または `run.register_post_review: true` を指定すると、merge back の後に完了判定を行い、todo / issue を自動 close できます。`--parallel <n>` は worktree モードでのみ指定できます。
736
773
 
774
+ `--branch <repo>=<name>` は、register の worktree モードでプロダクトの作業ブランチ名を上書きします。たとえば `specdojo exec run --project prj-0001 --register PJR-0012 --worktree --branch app1=feature/login` と指定します。複数のリポジトリにはオプションを繰り返します。宣言にないリポジトリ、同じリポジトリの重複、空の値、不正な Git ブランチ名は拒否します。別項目のブランチと重なると start 前に停止するため、topic を変えるかこの指定で解消します。自動の連番は付けません。SpecDojo の記帳用のブランチには適用しません。`--resume` では記録済みの名前を使うため指定の繰り返しは不要で、別名への変更は拒否します。
775
+
776
+ 作業ブランチ名の既定値は `exec/{project}-{id}` です。`repos[].branch_template` に git-flow の `feature/{topic}`、GitHub flow の `{type}/{topic}` などを設定できます。統合の形は `repos[].integration_strategy` の `merge`(既定)・`ff`・`branch-only` で選びます。`ff` は早送りできるときだけ統合し、分岐していれば停止します。自動の rebase や同期 merge は行いません。
777
+
737
778
  `--integration-branch <repo>=<branch>` は、register の worktree モードで、その run に限ってプロダクトリポジトリ `<repo>` の統合先を上書きします。複数リポジトリにはオプションを繰り返します。`<repo>` は `repos[].name` に宣言済みで、`<branch>` はそのリポジトリに存在する有効なローカルブランチでなければならず、リモートブランチの取得やローカルブランチの作成は行いません。同じ `<repo>` の重複、宣言にないリポジトリ、空の値は register の状態を変える前に拒否します。統合先の優先順位は「run の指定 → `repos[].integration_branch` → そのリポジトリの現在のブランチ」です。指定しない run の挙動は従来と変わりません。
738
779
 
739
780
  複数項目を `--parallel` で実行する場合、指定は選択された各 item run に同じように適用されます。中断した run を `--resume` するときは、開始時の指定を `pipeline-state.json` から再利用するため、オプションを繰り返す必要はありません。再開時に値を再指定する場合、その値は開始時の指定と一致する必要があり、run の途中で統合先を変更・追加する指定は拒否します。result の複数リポジトリ trace には、実際に使った統合先ブランチと統合後の commit snapshot が記録されます。
@@ -785,7 +826,7 @@ specdojo exec trial adopt --project prj-0001 --comparison <comparison-id> --tria
785
826
 
786
827
  `--agent`と任意の`--reporter-by`を使うと、reporterなしまたは全trial共通reporterの従来方式になります。`--pair <executor>=<reporter>...`は2組以上を指定し、executorとreporterを一組として比較します。`--pair`は`--agent` / `--reporter-by`と併用できません。比較記録の`reporter_mode`には`none` / `shared` / `paired`のいずれかを保存します。各reporterについて構造化出力の成否、形式試行回数、形式再試行回数、`evidence_blocked` / `invalid_output` / `invocation_failure` / `rate_limit`の失敗分類も保存します。`evidence_blocked` は reporter の申告ではなく、executor evidence から runner が機械判定した blocked を表します。
787
828
 
788
- `pipeline.parent_validations`に指定できるIDは`validate-schema`、`typecheck`、`test-unit`、`test-integration`、`lint-ts`、`lint-fm`、`lint-md`、`build`、`format-check`です(各IDは組み込み許可リストの固定argvへ解決されます)。`pipeline.parent_validations`はtrialにも適用され、executor成功後・reporter起動前に各worktreeで実行されます。親検証結果は`source: runner`付きでevidenceへ保存し、失敗時はtrialを`failed`にします。比較記録と`trial status`はexecutor・親検証・全体の時間を分け、executorの検証報告総数と`passed` / `failed` / `not_run` / `requires_human`、親検証の状態と件数を別々に表示します。採用前に親検証の成功、executorの未実施・未報告、sandbox 外で人が行う確認を確認してください。
829
+ `pipeline.parent_validations`に指定できるIDは`validate-schema`、`typecheck`、`test-unit`、`test-integration`、`lint-ts`、`lint-fm`、`lint-md`、`lint-mermaid`、`lint-d2`、`build`、`format-check`です(各IDは組み込み許可リストの固定argvへ解決されます)。`pipeline.parent_validations`はtrialにも適用され、executor成功後・reporter起動前に各worktreeで実行されます。親検証結果は`source: runner`付きでevidenceへ保存し、失敗時はtrialを`failed`にします。比較記録と`trial status`はexecutor・親検証・全体の時間を分け、executorの検証報告総数と`passed` / `failed` / `not_run` / `requires_human`、親検証の状態と件数を別々に表示します。採用前に親検証の成功、executorの未実施・未報告、sandbox 外で人が行う確認を確認してください。
789
830
 
790
831
  記録先は`execution_path/exec/trials/<comparison-id>/`です。agent選定への反映は自動化せず、人が複数比較を確認して `.specdojo/agent-members.yaml` を更新します。
791
832
 
@@ -1090,9 +1131,10 @@ schedule / register / job / routine の使い分けの基準は [exec運用ガ
1090
1131
 
1091
1132
  `agent` は、保存済みの plan を指定した1つの agent へ渡し、その標準出力を取得します。agent の選択は `.specdojo/agent-members.yaml` の nickname で一意に決まるため、実行のたびに担当が変わりません。決定論的な手順を shell script や CLI 側に置き、agent には判断だけを委ねるための最小の部品です。
1092
1133
 
1093
- | コマンド | 用途 |
1094
- | ----------- | ----------------------------------------------------------- |
1095
- | `agent run` | plan を stdin で agent へ渡し、標準出力をファイルへ保存する |
1134
+ | コマンド | 用途 |
1135
+ | -------------- | ----------------------------------------------------------------------- |
1136
+ | `agent run` | plan を stdin で agent へ渡し、標準出力をファイルへ保存する |
1137
+ | `agent launch` | agy を役割別セッション設定と runner の宣言済み task worktree で起動する |
1096
1138
 
1097
1139
  ```bash
1098
1140
  specdojo agent run --plan <plan.md> --by <nickname> --out <response.txt>
@@ -1136,9 +1178,10 @@ specdojo orchestrator night --project prj-0001 \
1136
1178
 
1137
1179
  `devcontainer` は、利用リポジトリの `.devcontainer/` 環境を構築するためのサブコマンドです。VS Code Dev Container などで、オーケストレーターを起動するための分離されたコンテナ環境を生成します。
1138
1180
 
1139
- | コマンド | 用途 |
1140
- | ----------------------- | ------------------------------------------- |
1141
- | `devcontainer scaffold` | `.devcontainer/` の設定ファイル群を生成する |
1181
+ | コマンド | 用途 |
1182
+ | -------------------------- | ----------------------------------------------------------------------- |
1183
+ | `devcontainer scaffold` | `.devcontainer/` の設定ファイル群を生成する |
1184
+ | `devcontainer host-script` | ホストから tmux へ接続するスクリプト本体を `.specdojo/host/` に書き出す |
1142
1185
 
1143
1186
  `devcontainer scaffold` は、指定された provider の CLI と、要求された追加機能を組み込んだ `devcontainer.json` と `post-create.sh` を生成します。あわせて、常時稼働ホストへの接続と tmux セッション維持のためのサンプルスクリプト(`.devcontainer/remote-host/specdojo-tmux.sh.sample`)と接続元 SSH 設定サンプル(`.devcontainer/remote-host/ssh-config.sample`)も生成します。provider は `antigravity`、`claude`、`codex`、`opencode` を指定できます。`--editor emacs` / `--editor vim` を指定した場合は、それぞれ Emacs 用の `emacs/init.el` / Vim 用の `vim/vimrc` も生成します。Dev Container は任意の実行環境であり、既存の Node.js 環境を置き換える必須手順ではありません。
1144
1187
 
@@ -1222,6 +1265,28 @@ post-create は `~/.emacs`、`~/.emacs.el`、`~/.emacs.d/init.el`、`~/.config/e
1222
1265
 
1223
1266
  Vim の雛形は `.devcontainer/vim/vimrc` に生成され、`~/.vimrc` と `~/.vim/vimrc` のどちらも無い場合だけ `~/.vimrc` へコピーされます。既存の Vim 設定は上書きしません。Emacs の雛形も上記と同じ上書き防止を維持します。
1224
1267
 
1268
+ ### 16.1. devcontainer host-script
1269
+
1270
+ `devcontainer host-script` は、常時稼働ホストから devcontainer 内の tmux セッションへ入るためのスクリプト本体(`.specdojo/host/devcontainer-tmux.sh`)をワークスペースへ書き出します。
1271
+
1272
+ ```bash
1273
+ npx specdojo devcontainer host-script
1274
+ ```
1275
+
1276
+ 主要オプション:
1277
+
1278
+ | オプション | 用途 |
1279
+ | ----------- | -------------------------------------------------------- |
1280
+ | `--dry-run` | 実際にファイルを作成せず、作成予定のファイルを表示する。 |
1281
+
1282
+ 本体スクリプトの対応 OS は macOS、Linux、Windows の WSL2 です。ホスト側のスクリプト(`~/bin/specdojo-tmux.sh` など)はワークスペースのパスを渡してこの本体スクリプトを呼び出す数行のみとなり、ホスト側スクリプトの保守負担を抑えられます。
1283
+
1284
+ - ラベル `devcontainer.local_folder` が一致する稼働中のコンテナがあれば、そのまま tmux へ入ります。
1285
+ - 停止中のコンテナがあれば `docker start` で起動してから入ります。この場合ホスト側に Node.js は不要です。
1286
+ - コンテナが存在しないときだけ `devcontainer up` を動かします。環境変数 `SPECDOJO_NODE_BIN` があればそこを `PATH` に足し、なければ利用者のログインシェル(`"$SHELL" -lic`)経由で起動します。mise を利用している場合は shims のディレクトリ(例: `~/.local/share/mise/shims`)を指定してください。
1287
+ - コンテナ内の作業ディレクトリはマウント情報から、実行ユーザーは `devcontainer.json` の `remoteUser` から求めます。求められないときは原因を stderr に出力して終了します。
1288
+ - スクリプトは実行権限(`0o755`)付きで書き出され、同じ版で複数回実行しても内容は変わりません。
1289
+
1225
1290
  ## 17. 関連ガイド
1226
1291
 
1227
1292
  | 詳細 | 参照先 |
@@ -121,6 +121,7 @@ exec の result の commit 前検査にも、利用リポジトリに設定が
121
121
  | -------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
122
122
  | `integration_branch` | `project/<project-id>/develop` | 別 project の作業ツリーから `register add --project <project-id> --commit` で直接記帳する統合ブランチです。 |
123
123
  | `project_context` | `["prj-overview"]` | edit / review plan へ常に渡す project 共通文書のローカル ID です。空配列 `[]` で無効化できます。`depends_on` や成果物の `based_on` は変更しません。 |
124
+ | `commit_types` | なし | 登録項目 type(`todo`・`issue` 等)から Conventional Commits type への対応マッピングです。 |
124
125
  | `run` | `{}` | agent 実行、worktree、登録日の表示に関する project 単位の設定です。 |
125
126
  | `repos` | なし | project のタスクが変更するプロダクトリポジトリの宣言です。詳細は「`repos`のキー」を参照してください。 |
126
127
 
@@ -188,16 +189,76 @@ project の `integration_branch` は、`repos[].integration_branch` とは別の
188
189
 
189
190
  `projects.<project-id>.repos` は、プロジェクトリポジトリとは別のプロダクトリポジトリを配列で宣言します。プロジェクトリポジトリ自身は宣言しません。キーを省略した project(または空配列)は、従来どおりプロジェクトリポジトリ 1 つだけを扱います。
190
191
 
191
- | キー | 必須 | 既定値 | 役割・利用箇所 |
192
- | ---------------------- | ---- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
193
- | `name` | 必須 | なし | `targets`・`paths` の接頭辞に使うリポジトリ名です。`[a-z0-9-]` だけを使い、project 内で一意です。`project` は予約名で使えません。 |
194
- | `path` | 必須 | なし | リポジトリのルートです。SpecDojo ルートからの相対パスで書き、実在するディレクトリを指します。 |
195
- | `integration_branch` | 任意 | そのリポジトリの現在のブランチ | exec が変更を統合する先のブランチです。exec branch もこのブランチの先端から作ります。 |
196
- | `integration_strategy` | 任意 | `merge` | `merge` はローカルの merge commit で統合します。`branch-only` は exec branch に commit して保持し、プロダクト側の PR レビューに渡します。 |
197
- | `setup` | 任意 | 両方 `true` | worktree 作成時の準備の有無です。`install`(依存導入)と `build`(生成物の build)を真偽値で指定します。 |
192
+ | キー | 必須 | 既定値 | 役割・利用箇所 |
193
+ | ------------------------- | ---- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
194
+ | `name` | 必須 | なし | `targets`・`paths` の接頭辞に使うリポジトリ名です。`[a-z0-9-]` だけを使い、project 内で一意です。`project` は予約名で使えません。 |
195
+ | `path` | 必須 | なし | リポジトリのルートです。SpecDojo ルートからの相対パスで書き、実在するディレクトリを指します。 |
196
+ | `integration_branch` | 任意 | そのリポジトリの現在のブランチ | exec が変更を統合する先のブランチです。exec branch もこのブランチの先端から作ります。 |
197
+ | `integration_strategy` | 任意 | `merge` | `merge` は merge commit、`ff` は早送りだけで統合します。`branch-only` は作業ブランチを保持してプロダクト側の PR レビューに渡します。 |
198
+ | `branch_template` | 任意 | `exec/{project}-{id}` | プロダクトの作業ブランチ名です。`{id}` または `{topic}` を含めます。 |
199
+ | `setup` | 任意 | 両方 `true` | worktree 作成時の準備の有無です。`install`(依存導入)と `build`(生成物の build)を真偽値で指定します。 |
200
+ | `commit_types` | 任意 | なし | このリポジトリ固有の登録項目 type から Conventional Commits type への対応マッピングです。project の指定より優先されます。 |
201
+ | `commit_subject_template` | 任意 | `exec(register {id}): {title}` | register の exec がプロダクトへ積む commit の 1 行目を指定します。 |
202
+ | `merge_message_template` | 任意 | `exec(register {id}): {title}` | register の exec がプロダクトへ積む merge commit のメッセージを指定します。改行で本文も指定できます。 |
198
203
 
199
204
  register の worktree 実行では、`exec run --integration-branch <repo>=<branch>` により `integration_branch` を run ごとに上書きできます。統合先の優先順位は「run の指定 → `repos[].integration_branch` → そのリポジトリの現在のブランチ」です。指定方法、ローカルブランチの検査、並列実行と再開時の扱いは [[specdojo:command-reference]] を参照してください。
200
205
 
206
+ `commit_types` は項目の type ごとに既定の commit type を上書きします。値は個票の `commit_type` と同じ 11 種類(`feat`・`fix`・`docs`・`refactor`・`test`・`chore`・`perf`・`build`・`ci`・`style`・`revert`)です。空文字や一覧外の値は設定読み込み時にエラーになります。未指定のキーは「個票の `commit_type` → `repos[].commit_types` → `projects.<project-id>.commit_types` → 既定対応」の順に解決します。`commit_scope` は個票で指定した場合だけ使います。
207
+
208
+ 既定対応は `issue` が `fix`、`todo`・`change-request`・`epic` が `feat`、`decision`・`note`・`question`・`risk` が `docs` です。未知の type は `chore` にフォールバックします。たとえば、project に `"commit_types": { "todo": "chore", "issue": "fix" }`、ドキュメント用の repo に `"commit_types": { "todo": "docs" }` を設定すると、その repo の todo は `docs`、他の repo の todo は `chore` になります。個票で `commit_type` を明示すれば、設定より優先されます。
209
+
210
+ `commit_subject_template` と `merge_message_template` はプロダクトリポジトリごとに独立して指定できます。設定がない場合は commit・merge とも従来の `exec(register <ID>): <タイトル>` を保ちます。SpecDojo の記録のリポジトリの start・review・wait・merge などの記帳には適用しません。
211
+
212
+ 使える変数は次の 8 種類です。未知の変数、対応しない波括弧、空白だけのテンプレートは設定エラーです。値の中の波括弧は再展開しません。
213
+
214
+ | 変数 | 値 |
215
+ | ----------- | --------------------------------------------------------------------------------------- |
216
+ | `{id}` | 登録項目の ID(例: `PJR-AB12`) |
217
+ | `{project}` | project ID(例: `prj-0001`) |
218
+ | `{topic}` | 個票ファイル名 `pjr-ab12-<topic>.md` の topic 部分。個票パスがない場合は小文字の項目 ID |
219
+ | `{type}` | 個票・repo・project・既定対応の優先順で解決した commit type |
220
+ | `{scope}` | 個票の `commit_scope`。未指定なら空文字 |
221
+ | `{title}` | 改行などの空白を 1 つにまとめた項目のタイトル |
222
+ | `{branch}` | そのプロダクトの実際の作業ブランチ名 |
223
+ | `{target}` | run の上書きを含む、そのプロダクトの実際の統合先 |
224
+
225
+ commit/merge の scope が空のときは、テンプレートに書いた `({scope})` を括弧ごと取り除きます。たとえば `{type}({scope}): {title}` は `feat: 機能追加` になります。commit のテンプレートは空白と改行を 1 つの空白にまとめて 1 行にします。merge のテンプレートは本文の改行を保ちます。どちらも 1 行目は従来どおり最大 100 文字(超過時は末尾を `…` にして切り詰める)です。本文の末尾には設定にかかわらず `Refs: <project-id>:<ID>` を付けます。テンプレート自身に同じ `Refs:` 行があっても、末尾に 1 回だけ置きます。
226
+
227
+ git-flow で develop へローカル統合する場合の `repos` 要素の例です。作業ブランチは `feature/{topic}` とし、`ff` で早送りだけを許可する例です。`merge_message_template` は `integration_strategy` を `merge` にした場合に使います。
228
+
229
+ ```json
230
+ {
231
+ "name": "app1",
232
+ "path": "../app1",
233
+ "integration_branch": "develop",
234
+ "branch_template": "feature/{topic}",
235
+ "integration_strategy": "ff",
236
+ "commit_subject_template": "{type}({scope}): {title}",
237
+ "merge_message_template": "Merge branch '{branch}' into {target}"
238
+ }
239
+ ```
240
+
241
+ GitHub flow で作業ブランチを保持して PR レビューへ渡す場合の例です。`branch-only` では runner が merge commit を作らないため、`merge_message_template` は使いません。作業ブランチ名には項目の commit type と topic を使います。
242
+
243
+ ```json
244
+ {
245
+ "name": "app1",
246
+ "path": "../app1",
247
+ "integration_branch": "main",
248
+ "integration_strategy": "branch-only",
249
+ "branch_template": "{type}/{topic}",
250
+ "commit_subject_template": "{type}: {title}"
251
+ }
252
+ ```
253
+
254
+ `branch_template` の変数は上表の `{project}`・`{id}`・`{topic}`・`{type}`・`{scope}`・`{title}` の 6 個です。`{branch}`・`{target}` は使えません。`{id}` も `{topic}` も含まない値、未知の変数、不正な波括弧、空白や `..` など Git のブランチ名に使えない文字を含む値は設定エラーです。展開後の名前も開始時に Git で検証し、空の scope や空白を含む title で不正になった場合は停止します。名前の自動修正・連番付与は行いません。register 以外のタスクでは `{topic}` は task ID の小文字、`{title}` は task ID、`{type}` は `feat`、`{scope}` は空文字です。
255
+
256
+ 名前の優先順位は、再開時の runner 記録 → `exec run --branch <repo>=<name>` → `branch_template` → 既定値です。別項目の記録や既存の管理外ブランチと名前が重なる場合は、register の start より前に停止し、topic の変更か `--branch` を案内します。同じ項目の再開では、設定や topic が変わっても記録された名前を使い、異なる `--branch` は拒否します。SpecDojo の記帳用リポジトリの `exec/{project}-{id}` は変更しません。
257
+
258
+ 対応記録は各プロダクトの Git 共通管理ディレクトリの `specdojo/product-branches/` に置き、項目の修飾 ID・ブランチ名・開始 commit を保存します。全 worktree とプロジェクトで共有し、名前の予約は排他的に作成します。再開と片付けはこの記録を参照し、`exec/` 以外の名前でも動きます。旧 run の記録がない場合だけ、従来の名前を互換用に探索します。
259
+
260
+ `ff` は統合先を作業ブランチの先端へ進め、merge commit を作りません。統合先が作業ブランチの祖先でない場合は、どのリポジトリも統合する前に理由を示して停止します。統合直前にも祖先関係を確かめ、checkout されていない統合先は比較交換で更新します。再開時にも `ff` の worktree へ統合先を自動 merge せず、rebase もしません。利用者が履歴を整理してから同じ run を再開します。`merge` の既定動作は変わりません。
261
+
201
262
  GitHub flow などで PR レビューを必須にするリポジトリには、`"integration_strategy": "branch-only"` を指定します。`integration_branch` は exec branch の作成元と、プロダクト側で PR を作る際の統合先の目安です。runner は統合先へ merge せず、push・PR 作成(`gh` を含む)も行いません。プロダクトの commit とプロジェクトの記帳が成功すると、プロジェクト側は通常どおり `review` へ進み、result に `branch-only`(未統合)、exec branch 名、trace key を残します。プロダクト側のレビューやリリースが完了したことは意味しません。
202
263
 
203
264
  成功後は全 worktree を撤去し、`branch-only` の exec branch だけを残します。利用者はその branch を必要な承認のもと push し、プロダクト側の手順で PR を作成します。squash merge でも追跡できるよう、commit メッセージの `Refs: <project-id>:<item-id>` を保持してください。失敗時は worktree と branch を残して `--resume` で再開し、`branch-only` の worktree へ統合先を自動で取り込みません。同じ項目を新規実行する際に保持済み branch があると停止するため、既存 run を再開するか、プロダクト側の作業を終えて branch を退避・削除してから実行します。`exec worktree prune` は未統合の branch を削除しません。
@@ -265,7 +326,7 @@ exec worktree の中で設定を読む場合(agent が worktree で `specdojo`
265
326
  - `name` がいずれかの project ID と同じである。`<name>:<...>` が doc id とリポジトリのパスのどちらか区別できなくなるためです。
266
327
  - `name` が予約名 `project` である。プロジェクトリポジトリの worktree のディレクトリ名と重なるためです。
267
328
  - `path` が空、絶対パス、存在しない、またはディレクトリでない。
268
- - 宣言に無いキーがある、`integration_branch` が空文字、`integration_strategy` が `merge` / `branch-only` 以外、`setup` の値が真偽値でない。
329
+ - 宣言に無いキーがある、`integration_branch` が空文字、`integration_strategy` が `merge` / `branch-only` / `ff` 以外、`setup` の値が真偽値でない。
269
330
 
270
331
  設定の形は `docs/specdojo/schemas/v1/specdojo-config.schema.yaml` でも検証できます。リポジトリ名と project ID の重複と `path` の実在は schema で表せないため、CLI の読み込み時の検証が正本です。
271
332