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
@@ -114,6 +114,19 @@ SpecDojo 自身のリポジトリへ起票する場合も、同じように別
114
114
 
115
115
  タイトルが日本語の場合は、内容を表す英語の `--topic` を小文字・ハイフン区切りで指定します。省略して `item` や日本語タイトル中の英単語だけが topic になった場合、`register add` は作成を続けたうえで警告します。警告後も、`register update --topic` で個票名と文書 ID を変更できます。成果物や kata(実践の型)を作成・修正する todo では、`--approach <approach> --target <doc-id>` を指定して進め方と対象を宣言できます(詳細は [exec運用ガイド](exec-operation-guide.md) の「register の todo から approach で成果物・kata を作る・直す手順」を参照してください)。
116
116
 
117
+ 対話で確かめた前提・制約・調査を任せる範囲は、`--input <text>` を繰り返して個票本文の `入力` 節へ記録します。完了条件は別に記載します。
118
+
119
+ ```bash
120
+ specdojo register add --project prj-0001 --type todo \
121
+ --title "技術案を作る" --topic technology-proposal \
122
+ --input "対象は社内向けの利用者100名" \
123
+ --input "認証方式の調査と選定を任せる"
124
+ ```
125
+
126
+ `register update --input` は入力一覧を置き換えます。追記したい場合も既存分を含めてすべて指定し、全削除は `--input -` 単独で行います。未指定なら保持し、空文字や削除と他の入力の混在は拒否します。節のない既存個票には更新時に節を追加します。変更は event の `input` に変更前後の JSON 配列(未入力は `-`)で残ります。同じ値への再更新は event を増やしません。
127
+
128
+ register 経由の plan では、approach がある成果物の plan と approach がない edit / investigate plan のどちらにも、入力がある場合だけ「個票の入力(前提)」が載ります。前提を読む範囲と完了を判定する条件を区別できます。
129
+
117
130
  `--priority` は次の目安で付けます(省略時は `medium`)。
118
131
 
119
132
  | priority | 目安 |
@@ -240,6 +253,8 @@ specdojo register close \
240
253
 
241
254
  `--commit` は register の worktree 実行の記帳・統合と同じ `register lifecycle` 枠が空くまで待ち、枠の内側で記帳、`register build` 相当の検証・再生成、commit を順に行います。commit 対象はそのコマンドが新たに変更した個票・event・参照文書だけで、開始前からあるほかの未 commit 変更は残します。対象個票やevent自体に開始前の変更がある場合は、既存差分を混ぜないため書き込み前に停止します。既定の件名は `docs(register PJR-XXXX): <command> <title>` で、`-m <message>` または `--message <message>` で上書きできます。`--dry-run` と同時に指定した場合は表示だけを行い、枠の取得と commit は行いません。
242
255
 
256
+ ほかのファイルがすでに stage されていても、初回 commit と hook 整形後の amend は対象パスだけを記録し、既存の staged 変更を保持します。stage 後の検査や commit・amend が失敗した場合は、そのコマンドが stage した対象だけを unstage し、作業ツリーの本文を残します。amend の失敗時は初回 commit も残るため、本文と HEAD の差分を確認してから再実行してください。
257
+
243
258
  別 project への起票では、対象登録簿全体が clean であることを追加で確認します。元の作業ツリーのブランチと HEAD は変更しません。
244
259
 
245
260
  ### 2.2. 個票の作成
@@ -387,7 +402,7 @@ specdojo register history --project <project-id> --since 2026-08-01 --json
387
402
  ```
388
403
 
389
404
  - `register add`、状態遷移、`register update`、`register renumber` は、現在値を個票へ、event を項目別イベントファイルへ書き込みます。`--by` と `--reason` を指定すると actor と理由を明示できます。記帳と再生成を `register lifecycle` 枠の内側で commit まで完了させる場合は `--commit` を付けます。
390
- - 一覧の列に現れない変更(対応結果本文の追記、個票 `status` の昇格など)は event になりません。個票の全差分が必要な場合は `git log -p` を使います。
405
+ - 入力は一覧に出なくても `input` の変更として event に記録します。それ以外の一覧の列に現れない変更(対応結果本文の追記、個票 `status` の昇格など)は event になりません。個票の全差分が必要な場合は `git log -p` を使います。
391
406
  - `--status-only` は追加・削除・状態遷移だけを残し、変更内容も遷移に関わる項目(`status` / `type` / `completed` / `conclusion`)へ絞ります。
392
407
  - `renumber` による ID 付け替えは、`id` の変更を含む `updated` イベントとして現れます。
393
408
  - 複数の遷移を1コミットへまとめたり squash したりしても、項目別イベントファイルに残る各 event の発生日時・actor・変更内容は失われません。`register start` を含む遷移時の commit policy は別の運用判断です。
@@ -84,8 +84,10 @@ npx specdojo devcontainer scaffold --provider claude,codex --editor emacs
84
84
 
85
85
  scaffold は、常時稼働ホストへの接続と tmux セッションの維持に使えるサンプルを `.devcontainer/remote-host/` に生成します。
86
86
 
87
- - `specdojo-tmux.sh.sample`: 常時稼働ホストの `~/bin/specdojo-tmux.sh` などへコピーし、実行権限(`chmod +x`)を付与して使います。devcontainer が停止していれば `devcontainer up` で起動し、コンテナ内の tmux セッション(`specdojo`)へ接続します。ホスト名や作業パスはプレースホルダーになっているため、ホストの環境に合わせて調整してください。
88
- - `ssh-config.sample`: 接続元端末の `~/.ssh/config` へ追加して使います。ホストへの通常接続エイリアスと、`RemoteCommand` と `RequestTTY force` で `specdojo-tmux.sh` を直接呼び出すエイリアス(`Host <host>-tmux`)を含みます。`RemoteCommand` では端末の `PATH` の設定が読み込まれないため、接続元から `ssh <host> 'command -v devcontainer'` を実行して Dev Container CLI が見つかるか確かめられます。
87
+ - `specdojo-tmux.sh.sample`: 常時稼働ホストの `~/bin/specdojo-tmux.sh` などへコピーし、実行権限(`chmod +x`)を付与して使います。workspace のパスを渡して、SpecDojo が配布する本体スクリプト(`.specdojo/host/devcontainer-tmux.sh`)を呼び出す数行のラッパーです。本体スクリプトは `npx specdojo devcontainer host-script` で workspace へ書き出せます。
88
+ - `ssh-config.sample`: 接続元端末の `~/.ssh/config` へ追加して使います。ホストへの通常接続エイリアスと、`RemoteCommand` と `RequestTTY force` で `specdojo-tmux.sh` を直接呼び出すエイリアス(`Host <host>-tmux`)を含みます。通常の接続(稼働中または停止中のコンテナ)では Node.js は不要(Docker のみ使用)です。コンテナ未作成時のみ Dev Container CLI が起動されます。
89
+
90
+ 本体スクリプト(`devcontainer-tmux.sh`)の対応 OS は macOS、Linux、Windows の WSL2 です。稼働中のコンテナがあればそのまま tmux へ入り、停止中のコンテナがあれば `docker start` で起動してから接続するため、通常の接続ではホスト側に Node.js は不要です。コンテナが存在しないときだけ `devcontainer up` を動かします。Dev Container CLI の場所は環境変数 `SPECDOJO_NODE_BIN` で上書きでき、mise を使う場合は shims のディレクトリ(例: `~/.local/share/mise/shims`)を設定します。指定がない場合は利用者のログインシェル(`"$SHELL" -lic`)経由で起動します。コンテナ内の作業ディレクトリはマウント情報から、実行ユーザーは `devcontainer.json` の `remoteUser` から自動で求めます。
89
91
 
90
92
  `devcontainer.json` の `appPort` や `forwardPorts` で開発サーバなどの公開ポートを設定している場合は、接続用エイリアスに `LocalForward` の行が含まれます。開発サーバのポートを増やしたときは、`~/.ssh/config` の tmux 接続用エイリアスにも `LocalForward <ポート> 127.0.0.1:<ポート>` を追加してください。
91
93
 
@@ -199,13 +201,38 @@ Host <ホスト名>
199
201
 
200
202
  ### 6.2. 実行環境の起動に失敗する
201
203
 
202
- SSH 経由の非対話シェル(`RemoteCommand` など)では、ログインシェルや対話端末で読み込まれる `~/.zshrc` などの `PATH` の設定が読み込まれないため、コンテナ起動用のコマンドが見つからない場合があります。接続元から次を実行して確認します。
204
+ 新方式では、稼働中または停止中のコンテナへの接続は Docker コマンドのみで行うためホスト側に Node.js は不要です。コンテナが存在しない初回起動時のみ、`devcontainer up` を動かします。
205
+
206
+ SSH 経由の非対話シェル(`RemoteCommand` など)では、ログインシェルや対話端末で読み込まれる `~/.zshrc` などの `PATH` の設定が読み込まれず、Docker や起動用コマンドが見つからない場合があります。本体スクリプトは、最初に Docker を呼ぶ前に次の順序で実行ファイルを探します。
207
+
208
+ 1. `SPECDOJO_DOCKER_BIN` が指定されていれば、そのディレクトリの `docker` を使用する。
209
+ 2. 現在の `PATH` で探す。
210
+ 3. ログインシェル(`"$SHELL" -lc`。`SHELL` が未設定なら `/bin/bash`)に `command -v docker` を問い合わせる。起動時のメッセージは無視し、実行できるファイルのパスだけを採る。
211
+ 4. `/usr/local/bin`、`/opt/homebrew/bin`、`$HOME/.docker/bin`、`/Applications/Docker.app/Contents/Resources/bin`、`/snap/bin`、`/usr/bin` の順に探す。
212
+
213
+ 見つかったディレクトリを `PATH` の先頭へ追加し、以降の Docker 呼び出しと `devcontainer up` に引き継ぎます。`SPECDOJO_DOCKER_BIN` に指定するのは実行ファイル自体ではなく、`docker` があるディレクトリです。明示指定が無効な場合は、ほかの場所に切り替えずエラーで停止します。SSH の接続先で、例えば次のように指定できます。
214
+
215
+ ```bash
216
+ SPECDOJO_DOCKER_BIN=/opt/homebrew/bin bash .specdojo/host/devcontainer-tmux.sh /path/to/workspace
217
+ ```
218
+
219
+ Docker が見つからない場合は、探索した場所と OS ごとの対処方法を標準エラーへ出して終了コード 1 で停止します。見つかっても `docker info` に失敗すれば、コンテナを探す前に同様に停止します。
220
+
221
+ | ホスト | Docker が見つからないとき | `docker info` が失敗するとき |
222
+ | ------------ | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
223
+ | macOS | Docker Desktop を導入する | Docker Desktop を起動し、Docker context を確認する |
224
+ | Windows WSL2 | Docker Desktop を起動し、対象ディストリビューションの WSL integration を有効にする | Docker Desktop の起動と WSL integration を確認する |
225
+ | Linux | Docker Engine を導入する | docker サービスを起動し、`docker` グループへの所属を確認してログインし直す |
226
+
227
+ 既存の workspace へ本体の更新を反映するには、更新後の SpecDojo で `npx specdojo devcontainer host-script` を再実行します。ホスト側のラッパーはそのまま使えます。
228
+
229
+ コンテナ未作成時の Dev Container CLI の探索は、接続元から次を実行して確認します。
203
230
 
204
231
  ```bash
205
232
  ssh <ホスト名> 'command -v devcontainer'
206
233
  ```
207
234
 
208
- `devcontainer` が見つからない場合は、ホスト側の通常端末で `dirname "$(command -v devcontainer)"` を実行して場所を確認し、`specdojo-tmux.sh` の `node_bin_dir` に設定してください。詳細な `PATH` を確認する場合は次を実行します。
235
+ `devcontainer` が見つからない場合は、ホスト側の環境変数 `SPECDOJO_NODE_BIN` に Dev Container CLI や Node.js の bin ディレクトリを設定してください。mise を使う場合は shims のディレクトリ(例: `~/.local/share/mise/shims`)を指定します。詳細な `PATH` を確認する場合は次を実行します。
209
236
 
210
237
  ```bash
211
238
  ssh <ホスト名> 'printf "PATH=%s\n" "$PATH"; command -v node || true; command -v devcontainer || true'
@@ -19,7 +19,7 @@ SpecDojo は道場のメタファーとして、進め方(`approach`)を「R
19
19
 
20
20
  **この文書で分かること**
21
21
 
22
- - `approach` の選び方と一覧、参照の共通原則、実践の型メンテナンスの進め方、review への適用
22
+ - `approach` の選び方と一覧、`draft` と `fully-guided` の使い分け、文脈の置き場所の使い分け、参照の共通原則、実践の型メンテナンスの進め方、review への適用
23
23
 
24
24
  **次に読む文書**
25
25
 
@@ -42,17 +42,21 @@ SpecDojo は道場のメタファーとして、進め方(`approach`)を「R
42
42
 
43
43
  ### 1.1. approach の選び方
44
44
 
45
- 進め方は、まずタスクの目的で分かれ、通常の成果物作成・更新では実践の型の整備状況でさらに分かれます。`fully-guided` / `recipe-guided` / `freeform` は実践の型をどこまで基準にするかを表します。`retrofit` は実装先行時の現在動作調査、`bootstrap` / `cross-deliverable-dedup`・各 `*-authoring`・各 `*-maintenance`・`finalize` 系は、それぞれの目的に応じて選ぶ進め方です。
45
+ 進め方は、まずタスクの目的で分かれ、文脈で任された範囲を調べて下書きする場合は `draft`、既存成果物を磨き込む場合は `fully-guided` を選びます。その他の成果物作成・更新では実践の型の整備状況でさらに分かれます。`fully-guided` / `recipe-guided` / `freeform` は実践の型をどこまで基準にするかを表します。`retrofit` は実装先行時の現在動作調査、`bootstrap` / `cross-deliverable-dedup`・各 `*-authoring`・各 `*-maintenance`・`finalize` 系は、それぞれの目的に応じて選ぶ進め方です。
46
46
 
47
47
  ```mermaid
48
48
  flowchart TD
49
49
  P{"タスクの目的"}
50
- P -->|"成果物を作成・更新する"| M{"実践の型の整備状況"}
51
- M -->|"必要な型が揃い信頼できる"| FG["fully-guided"]
50
+ P -->|"任された文脈を調べて下書きする"| DR["draft"]
51
+ SC["雛形 → 人が文脈を記入"] --> DR
52
+ DR --> FG["fully-guided<br/>既存成果物を磨き込む"]
53
+ P -->|"既存成果物を磨き込む"| FG
54
+ P -->|"その他の成果物作成・更新"| M{"実践の型の整備状況"}
55
+ M -->|"必要な型が揃い信頼できる"| FG
52
56
  M -->|"recipe のみ使える"| RG["recipe-guided"]
53
57
  M -->|"実践の型に頼れない"| FF["freeform"]
54
- FG --> W["雛形から開始 → 内容を記述 → レビュー"]
55
- RG --> W
58
+ FG --> RV["レビュー → finalize(人が確定)"]
59
+ RG --> W["雛形から開始 → 内容を記述 → レビュー"]
56
60
  FF --> W
57
61
  P -->|"実装先行の成果物を反映・新設"| RF["retrofit<br/>実装 → 成果物"]
58
62
  P -->|"成果物と実践の型を新規に一括整備"| BS["bootstrap"]
@@ -62,7 +66,7 @@ flowchart TD
62
66
  P -->|"human が確定する"| FIN["finalize / bootstrap-finalize<br/>status を ready へ昇格"]
63
67
  ```
64
68
 
65
- 整備状況で分岐するのは成果物の作成・更新(`fully-guided` / `recipe-guided` / `freeform`)だけです。`bootstrap` / `retrofit` / `cross-deliverable-dedup` / 各 `*-maintenance` / `finalize` 系は目的別のフェーズであり、実践の型が何件そろっているかだけでは選びません。とくに `bootstrap` は「実践の型が1件でも欠ける」ことを理由に選ばず、`undecided` の型を含めてどの型が必要かを作成条件に照らして判断し、成果物と必要な型を一式で初期整備する場合に限って選びます。不要な recipe / sample / template は rulebook frontmatter へ `not-needed` と宣言し、作成対象へ含めません。基準にできる実践の型が無くても、初期整備の対象でなければ `freeform` です。
69
+ `draft` は文脈で任された調査・下書きのための段であり、型の件数からは自動選択しません。整備状況で分岐するのは成果物の作成・更新(`fully-guided` / `recipe-guided` / `freeform`)だけです。`bootstrap` / `retrofit` / `cross-deliverable-dedup` / 各 `*-maintenance` / `finalize` 系は目的別のフェーズであり、実践の型が何件そろっているかだけでは選びません。とくに `bootstrap` は「実践の型が1件でも欠ける」ことを理由に選ばず、`undecided` の型を含めてどの型が必要かを作成条件に照らして判断し、成果物と必要な型を一式で初期整備する場合に限って選びます。不要な recipe / sample / template は rulebook frontmatter へ `not-needed` と宣言し、作成対象へ含めません。基準にできる実践の型が無くても、初期整備の対象でなければ `freeform` です。
66
70
 
67
71
  ### 1.2. approach 一覧
68
72
 
@@ -70,9 +74,9 @@ flowchart TD
70
74
 
71
75
  #### 1.2.1. 成果物の作成・更新
72
76
 
73
- 実践の型をどこまで作成・更新の基準にするかを切り替える進め方です。
77
+ `draft` は下書き、`fully-guided` は磨き込みを担います。基本の流れは、雛形 → 人が文脈を記入 → `draft` → `fully-guided` → `finalize`(人)です。`recipe-guided` / `freeform` は実践の型をどこまで基準にするかを切り替えます。
74
78
 
75
- この三つの流は、型との関係を表す守破離に対応します。「守」は型をそのまま守り、「破」は型を基準にしながら工夫し、「離」は型から離れて完了条件と根拠から組み立てます。守破離は品質の序列ではなく、タスクの目的と実践の型の整備状況に応じて進め方を選ぶための名前です。
79
+ `draft` を除く三つの流は、型との関係を表す守破離に対応します。「守」は型をそのまま守り、「破」は型を基準にしながら工夫し、「離」は型から離れて完了条件と根拠から組み立てます。守破離は品質の序列ではなく、タスクの目的と実践の型の整備状況に応じて進め方を選ぶための名前です。
76
80
 
77
81
  ```mermaid
78
82
  flowchart LR
@@ -83,18 +87,103 @@ flowchart LR
83
87
  CTX["類似成果物・<br/>プロジェクト文脈"]
84
88
  D["成果物"]
85
89
 
86
- RB -->|fully-guided| D
87
- RC -->|fully-guided / recipe-guided| D
88
- SP -->|fully-guided| D
89
- TP -->|fully-guided| D
90
+ RB -->|draft / fully-guided| D
91
+ RC -->|draft / fully-guided / recipe-guided| D
92
+ SP -->|draft / fully-guided| D
93
+ TP -->|draft| D
94
+ CTX -->|draft| D
95
+ EXT["外部の情報(出典つき)"] -->|draft:任された範囲| D
90
96
  CTX -->|freeform| D
91
97
  ```
92
98
 
93
- | `approach` | 流の名前 | 参照方針と進め方 | 対応テンプレート |
94
- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
95
- | `fully-guided` | 守 | 必要と宣言された rulebook / recipe / sample / template をそれぞれの役割に沿って使う。利用する template があればそこから開始し、rulebook と矛盾する場合は rulebook を正とする | [edit](../exec-templates/xep-fully-guided-template.md) / [review](../exec-templates/xrp-fully-guided-template.md) |
96
- | `recipe-guided` | 破 | recipe が示す構成・問い・観点を主基準にする。rulebook / sample / template が存在しても、構造・文体の基準にはしない | [edit](../exec-templates/xep-recipe-guided-template.md) / [review](../exec-templates/xrp-recipe-guided-template.md) |
97
- | `freeform` | 離 | 実践の型に頼れないため、カタログの `done_criteria`、対応 schema、既存の類似成果物を根拠に構成と内容を決める。参照した根拠と未決事項を result に残す | [edit](../exec-templates/xep-freeform-template.md) / [review](../exec-templates/xrp-freeform-template.md) |
99
+ | `approach` | 流の名前 | 参照方針と進め方 | 対応テンプレート |
100
+ | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
101
+ | `draft` | 下書き | 文脈で任された範囲を調べて下書きする。型・依存成果物・`based_on`・`project_context`・個票の `入力`・カタログの `brief`・成果物内の文脈・出典つき外部情報を参照する。選定値を提案として示し、出典と選定理由を result に残す | `xep-draft-template.md`(edit) |
102
+ | `fully-guided` | 守 | 既存成果物の磨き込み専用。宣言された rulebook / recipe / sample、`depends_on`、`based_on`、`project_context`、個票の `入力`、カタログの `brief` だけを参照する。template は読み込まない | [edit](../exec-templates/xep-fully-guided-template.md) / [review](../exec-templates/xrp-fully-guided-template.md) |
103
+ | `recipe-guided` | 破 | recipe が示す構成・問い・観点を主基準にする。rulebook / sample / template が存在しても、構造・文体の基準にはしない | [edit](../exec-templates/xep-recipe-guided-template.md) / [review](../exec-templates/xrp-recipe-guided-template.md) |
104
+ | `freeform` | 離 | 実践の型に頼れないため、カタログの `done_criteria`、対応 schema、既存の類似成果物を根拠に構成と内容を決める。参照した根拠と未決事項を result に残す | [edit](../exec-templates/xep-freeform-template.md) / [review](../exec-templates/xrp-freeform-template.md) |
105
+
106
+ ##### draft と fully-guided の使い分け
107
+
108
+ `draft` と `fully-guided` は、未作成または下書き段階の成果物を段階的に仕上げるために組み合わせて使います。
109
+
110
+ | 観点 | `draft`(下書き) | `fully-guided`(磨き込み) |
111
+ | ----------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
112
+ | 目的 | 文脈で任された調査・技術選定を行い、下書きを作成する | 既存の草案を実践の型に適合させ、構造・用語・整合性を磨き込む |
113
+ | 根拠のない具体化 | **任された範囲に限り解除**。外部情報(Web や公式資料)を調べて値を決めてよい | **厳格に禁止**。宣言された文書で裏付けが取れる範囲のみ修正・補完する |
114
+ | 外部調査・選定 | 行う。選定した値は成果物内で「提案」として示し、出典と選定理由を result に残す | 行わない。新たな外部探索や独自選定はせず、既存記述を整理する |
115
+ | template の参照 | 参照する(雛形から章構成や初期記述を起こす) | 参照しない(既に草案があるため型のみ参照) |
116
+ | 文脈の目印 `_CONTEXT_:` | 指示を本文へ反映したら目印を削除し、元の指示と選定内容を result に写す | 反映・削除しない。残存している指示は未決論点(_TODO_)として result に残す |
117
+ | 主な適用タイミング | 成果物の新規作成時、技術スタックや方式の調査・選定を agent に委任する段 | `draft` による草案作成後、または既存成果物の改訂・品質向上を行う段 |
118
+
119
+ ##### 文脈の置き場所の使い分け
120
+
121
+ 文脈(前提・制約・調査委任の指示)を agent に渡す場所には、成果物内の `_CONTEXT_:`、個票の `入力`(`--input`)、カタログの `brief` の 3 つがあります。それぞれの特徴と適した用途に応じて使い分けます。
122
+
123
+ | 置き場所 | 指定方法 | 特徴と適した用途 | ライフサイクル・反映先 |
124
+ | -------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
125
+ | 成果物内の `_CONTEXT_:` | 成果物の対象段落の先頭に `_CONTEXT_:` と記述(文書全体なら先頭章、特定項目なら該当見出し直下) | 特定の章や構成に局所化した指示、雛形を確認しながらその場で書き込みたい前提・調査指示 | `draft` が本文反映後に削除して result に記録。`finalize` 時や `status: ready` で残っていれば lint で error |
126
+ | 個票の `入力`(`--input`) | `register add` / `register update` の `--input <text>` で指定 | オーケストレーターや人との対話から得た前提、単発の制約、調査・選定の委任範囲。成果物ファイルを開かずに起票時に渡したい文脈 | 個票の「入力」節に記録され、register 経由の plan に前提として展開される |
127
+ | カタログの `brief` | カタログ(`dct-*.yaml`)の成果物定義に `brief: \|` で記述 | プロジェクトや成果物群全体で継続して渡したい共通前提(採用技術スタック、基盤条件など)。複数成果物で YAML アンカー(`&anchor` / `*anchor`)による共有が可能 | カタログに保持され、schedule と register の両経路の plan に一貫して前提として展開される |
128
+
129
+ ##### 文脈を渡して作成する具体例(TSD の技術選定)
130
+
131
+ たとえば、技術スタック詳細定義(TSD)を「静的サイトで主流の技術スタックで書く」と指示して作成する場合、文脈の置き場所によって次のように渡します。
132
+
133
+ - **カタログの `brief` で渡す場合(プロジェクト共通の前提)**:
134
+ Web サイト構築プロジェクトで、サイト全体の技術方針として静的サイト構成を採用することがあらかじめ決まっている場合、カタログの成果物エントリに `brief` として定義します。
135
+
136
+ ```yaml
137
+ specdojo:
138
+ id: prj-0001:cxd-specdojo
139
+ # ...
140
+ deliverables:
141
+ - id: tsd-frontend-site
142
+ name: "フロントエンド技術スタック詳細定義"
143
+ rulebook: specdojo:tsd-rulebook
144
+ brief: |
145
+ 静的サイト構成を採用する。主流の技術スタック(Astro 等)を基本とし、ビルド性能と拡張性を重視する。
146
+ ```
147
+
148
+ - **個票の `入力`(`--input`)で渡す場合(対話からの委任指示)**:
149
+ 対話を通じて「静的サイトで主流の技術スタックを調べて下書きしてほしい」と決まった場合、成果物ファイルを開かずに起票コマンドで前提を渡します。
150
+
151
+ ```bash
152
+ specdojo register add \
153
+ --project prj-0001 \
154
+ --type todo \
155
+ --title "フロントエンドTSDの下書き" \
156
+ --approach draft \
157
+ --target prj-0001:tsd-frontend-site \
158
+ --input "静的サイトで主流の技術スタック(Astro 等)を調査し、選定理由と構成を下書きする"
159
+ ```
160
+
161
+ - **成果物内の `_CONTEXT_:` で渡す場合(章ごとの局所的な指示)**:
162
+ まず `deliverable scaffold` で成果物の雛形を作成します。カタログにある成果物は `--target` で 1 件だけ指定して作成でき、カタログにない成果物は `--target-path` と `--target-rulebook` を添えて作成します(template のない rulebook でも `deliverable_type` を引き継いだ最小雛形が生成されます)。
163
+
164
+ ```bash
165
+ # カタログにある成果物を 1 件だけ指定して作成する場合
166
+ specdojo deliverable scaffold \
167
+ --project prj-0001 \
168
+ --target prj-0001:tsd-frontend-site
169
+
170
+ # カタログにない成果物を雛形にする場合
171
+ specdojo deliverable scaffold \
172
+ --project prj-0001 \
173
+ --target prj-0001:tsd-custom-tool \
174
+ --target-path docs/ja/projects/prj-0001/architecture/tsd-custom-tool.md \
175
+ --target-rulebook specdojo:tsd-rulebook
176
+ ```
177
+
178
+ 雛形を作成した後、特定の章(「採用技術・設定」章など)に直接指示を置きたい場合に記述します。
179
+
180
+ ```markdown
181
+ ## 4. 採用技術・設定
182
+
183
+ _CONTEXT_: 静的サイトで主流の技術スタック(Astro 等)を調査し、選定したフレームワークやライブラリの採用値・選定理由・反映方法を提案として表にまとめてください。
184
+ ```
185
+
186
+ `draft` はこの指示を読んで外部情報を調査し、選定値を「提案」として記述した上で `_CONTEXT_:` を削除し、result に出典・選定理由と元の指示を記録します。続く `fully-guided` が、その草案を tsd の型に合わせて磨き込みます。
98
187
 
99
188
  #### 1.2.2. 初期整備・実装反映・横断整理
100
189
 
@@ -198,16 +287,17 @@ flowchart LR
198
287
 
199
288
  `approach` にかかわらず適用する原則です。
200
289
 
201
- - 矛盾時の優先: `fully-guided` は rulebook(規約)を優先し、template の章構成が食い違っても rulebook を正とします。`recipe-guided` は rulebook を参照範囲に含めないため recipe を優先します。
202
- - 参照範囲: `fully-guided` / `recipe-guided` および未指定では、対象成果物に紐づく実践の型・`depends_on` 成果物・プロジェクトコンテキスト(→ [遂行の技活用ガイド](waza-guide.md))に限定し、他のプロジェクト文書を独自に探索しません。`freeform` は類似実例やプロジェクト文脈を参照するため対象外です。
290
+ - 矛盾時の優先: `draft` / `fully-guided` は rulebook(規約)を優先し、template の章構成が食い違っても rulebook を正とします。`recipe-guided` は rulebook を参照範囲に含めないため recipe を優先します。
291
+ - 参照範囲: `fully-guided` は宣言された文書だけを参照します。対象成果物、rulebook / 併せて適用する rulebook / recipe / sample、`depends_on` 成果物、対象成果物 frontmatter の `based_on`、`project_context`、個票の `入力`、カタログの `brief` を含み、未宣言の文書や外部の情報は探索しません。`入力` と `brief` は未指定なら plan に載りません。`draft` はこれらに template・成果物内の文脈・任された調査に必要な出典つき外部情報を加えます。`recipe-guided` および未指定では、対象成果物に紐づく実践の型・`depends_on` 成果物・プロジェクトコンテキスト(→ [遂行の技活用ガイド](waza-guide.md))に限定し、他のプロジェクト文書を独自に探索しません。`freeform` は類似実例やプロジェクト文脈を参照するため対象外です。
203
292
  - 既存記述の尊重: `fully-guided` / `recipe-guided` および未指定では既存記述を尊重し、`depends_on` の最新の決定と矛盾する箇所、および参照範囲に含む実践の型に適合しない箇所(rulebook を参照範囲に含む `fully-guided` / 未指定では、rulebook の必須要素の欠落・禁止事項への抵触・章構成の不適合)のみ最小限を修正し、不足は加筆・補強します。実践の型への適合は内容の全面書き換えではなく、既存記述を保持したままの章立ての移し替えと必須要素の補完として行います。あわせて、同一成果物内で重複している記述は正本を1箇所に定めて統合し、参照範囲に含む実践の型の必須要素にも `done_criteria` にも寄与しない記述は削除します(rulebook を参照範囲に含む `fully-guided` / 未指定では rulebook の必須要素が基準)。統合・削除は既存記述の尊重の例外であり、判断根拠を result に記録することで担保します。`freeform` は対象外です。上記のいずれにも該当しない場合(完成度・整合性・読みやすさの向上など)は、それだけを理由に修正しません。rulebook が複数の構成を許容している場合(例: 領域単位・グループ単位のいずれの粒度も認める場合)、他章との見た目の整合を理由により詳細な構成へ書き換えません。
204
- - 根拠のない具体化の禁止: `freeform` を除き、ファイルパス・コマンド・設定値など実装や設定の実態を示す記述を新たに書き加える場合、参照範囲の文書(rulebook / recipe / `depends_on` 成果物・プロジェクトコンテキスト、`retrofit` では `evidence_refs`)で裏付けが取れる場合に限ります。既存記述が曖昧・不完全でも、裏付けが無ければ完成度を上げる目的だけで断定的に具体化しません。裏付けの無い箇所は _TODO_ / _ASSUMPTION_ として論点を残します。品質上の根拠不足は grade が該当 viewpoint の level と finding で評価し、review はその評価を付け直しません。
293
+ - 根拠のない具体化の禁止: `freeform` と `draft` の文脈で任された範囲を除き、ファイルパス・コマンド・設定値など実装や設定の実態を示す記述を新たに書き加える場合、参照範囲の文書(rulebook / recipe / `depends_on` 成果物・プロジェクトコンテキスト、`fully-guided` ではさらに `based_on`・個票の `入力`・カタログの `brief`、`retrofit` では `evidence_refs`)で裏付けが取れる場合に限ります。既存記述が曖昧・不完全でも、裏付けが無ければ完成度を上げる目的だけで断定的に具体化しません。`draft` では任された範囲に限って調べて値を決め、成果物に「提案」と示し、出典と選定理由を result に残します。任されていない範囲や裏付けの無い箇所は _TODO_ / _ASSUMPTION_ として論点を残します。品質上の根拠不足は grade が該当 viewpoint の level と finding で評価し、review はその評価を付け直しません。
205
294
  - 判断根拠の記録: 参照した文書・しなかった文書とその理由を成果物または result に残します(特に `recipe-guided` / `freeform`)。後から実践の型を整備する材料になります。
206
295
  - 判定基準の優先: `done_criteria` と grade 結果が判定基準を示す場合はそれらを優先します。本原則は、判定基準だけでは読み取れない「どこまで参照に照らすか」を補います。
296
+ - 前提・概要・判定基準の使い分け: カタログの `overview`(成果物の目的を1文で表す概要)、`brief`(成果物の外から継続して渡す技術スタックや制約などの前提)、`done_criteria`(成果物が満たすべき検証可能な完了条件)を明確に区別します。`brief` は schedule / register 両経路の plan に前提として展開され、未指定なら plan に載りません。複数の成果物で前提を共有する場合は YAML アンカー(`&anchor` / `*anchor`)を活用できます。前提を完了条件に混同せず、検証可能な基準だけを `done_criteria` に記載します。
207
297
 
208
298
  ### 1.4. 成果物カタログなしで進める
209
299
 
210
- register からの `fully-guided`・`recipe-guided`・`freeform`・`retrofit`・`bootstrap`・`finalize`・`bootstrap-finalize` は、カタログなしでも使えます。既存成果物は `--target <doc-id>` を文書索引で引き、frontmatter の `specdojo.rulebook` を起点に kata を辿ります。新規成果物は `register add`・`register update` の `--target-path` と `--target-rulebook` にパスと rulebook ID を明示します。個票へ保存する名前は `target_path` と `target_rulebook` です。既存文書と指定が矛盾した場合は停止します。
300
+ register からの `draft`・`fully-guided`・`recipe-guided`・`freeform`・`retrofit`・`bootstrap`・`finalize`・`bootstrap-finalize` は、カタログなしでも使えます。既存成果物は `--target <doc-id>` を文書索引で引き、frontmatter の `specdojo.rulebook` を起点に kata を辿ります。新規成果物は `register add`・`register update` の `--target-path` と `--target-rulebook` にパスと rulebook ID を明示します。個票へ保存する名前は `target_path` と `target_rulebook` です。既存文書と指定が矛盾した場合は停止します。
211
301
 
212
302
  カタログの `done_criteria` はないため、個票の完了条件と rulebook を完了基準にします。`fully-guided` には `not-needed` を除く kata 一式、`recipe-guided` には recipe が必要で、不足すると起票時に停止します。`retrofit` では調べる実装のパスを個票に明記します。
213
303
 
@@ -240,7 +330,8 @@ review でも「整備状況に応じた進め方(approach)」を使いま
240
330
 
241
331
  通常の成果物編集では観点別の自己レビューを行わず、`done_criteria` を「完了の狙い」として扱います。多観点での品質評価と証跡は grade が担い、独立した review は grade 結果を事実としてタスクの完了可否を判断します。以下の `approach` ごとの参照方針は、編集時の記述と review の照合範囲に適用します。
242
332
 
243
- - `fully-guided`: rulebook / recipe / sample / template と、そこから edit plan に展開された作業範囲を照合します。品質上の適合性は grade 結果を使い、review が新しい level や finding を付けません。
333
+ - `draft`: 文脈で任された範囲の下書き、提案の表示、出典と選定理由・元の指示の記録をタスクの完了条件と照合します。
334
+ - `fully-guided`: 宣言された参照と、edit plan に展開された既存成果物の磨き込み範囲を照合します。品質上の適合性は grade 結果を使い、review が新しい level や finding を付けません。
244
335
  - `recipe-guided`: recipe と edit plan に限定して作業範囲を照合し、rulebook / sample / template を新たな判定基準として持ち込みません。
245
336
  - `freeform`: カタログの `done_criteria`、対応 schema、edit plan が示した既存の類似成果物やプロジェクト文脈を、完了条件の照合資料として使います。
246
337
  - `rulebook-maintenance` / `recipe-maintenance` / `sample-maintenance` / `template-maintenance`: 「実践の型メンテナンスの進め方」に従い、対象の実践の型と edit plan の完了条件を照合します。実践の型そのものの品質評価は、review 前段の kata grade を使います。
@@ -358,21 +358,48 @@ phase や owner rule に書く `approach` は、タスクの目的と実践の
358
358
 
359
359
  | 段階 | 正本・担当 | 出力 |
360
360
  | -------- | -------------------------------------- | ------------------------------------------------------------ |
361
- | 目的宣言 | strategy の `approach_rules` | 7 種の `intent` と必要な target / scope |
361
+ | 目的宣言 | strategy の `approach_rules` | 8 種の `intent` と必要な target / scope |
362
362
  | 品質評価 | `specdojo grade` | grade result サイドカーの保存済み `verdict` |
363
363
  | 事実収集 | コード | 実在、要否宣言、参照切れ、実装エビデンス |
364
364
  | 規則適用 | コード(`schedule strategy generate`) | 成果物ごとの approach |
365
365
  | 構造生成 | コード(`schedule strategy generate`) | scope・profile・owner・gate・依存・milestone を持つ strategy |
366
366
 
367
- - `TaskIntent` 7 種は `author-deliverable`、`bootstrap-kata-set`、`reflect-implementation`、`deduplicate-across-deliverables`、`improve-kata`、`confirm-deliverable`、`confirm-with-kata-set` です。同じ track や owner rule 内でも成果物ごとに別の rule へ分けられます。
367
+ - `TaskIntent` 8 種は `author-deliverable`、`draft-with-context`、`bootstrap-kata-set`、`reflect-implementation`、`deduplicate-across-deliverables`、`improve-kata`、`confirm-deliverable`、`confirm-with-kata-set` です。同じ track や owner rule 内でも成果物ごとに別の rule へ分けられます。
368
368
  - `author-deliverable` は grade が `pass` の Kata を利用可能とし、`fully-guided` / `recipe-guided` / `freeform` を導出します。他の intent は目的別の `bootstrap` / `retrofit` / 横断整理 / maintenance / finalize 系へ一意に写像します。
369
369
  - `bootstrap` は `bootstrap_scope`(作成条件から必要と判断し、一式で初期整備する実践の型)と理由の記載が必要です。`not-needed` またはすべて利用可能な型を対象にできません。`retrofit` は解決済みの `evidence_refs` が 1 件以上必要です。
370
370
  - intent の欠落・重複、必要な grade や追加パラメータの欠落、参照切れがある場合は暫定 approach を使わず生成を停止します。
371
- - 標準 profile は `bootstrap`、`retrofit`、`fully-guided`、`recipe-guided`、`freeform`、4種の maintenance、横断整理、`finalize` / `bootstrap-finalize` を、固定の phase ID・suffix・duration・execution・mode・agent pipeline へ写像します。`not-needed` の型に対応する maintenance は生成せず、成果物ごとに異なる profile は `owner_rules[].phase_sets` で分けます。
371
+ - 標準 profile は `bootstrap`、`retrofit`、`draft`、`fully-guided`、`recipe-guided`、`freeform`、4種の maintenance、横断整理、`finalize` / `bootstrap-finalize` を、固定の phase ID・suffix・duration・execution・mode・agent pipeline へ写像します。`not-needed` の型に対応する maintenance は生成せず、成果物ごとに異なる profile は `owner_rules[].phase_sets` で分けます。
372
372
  - owner は明示オプション、既存 strategy、既定 owner の順に解決します。DCT の `done_criteria.roles` はレビュー観点なので、主担当へ流用しません。
373
373
  - generator は書き込み前に `schedule build --dry-run` 相当を実行します。全 strategy の project ID、参照、schema、milestone ID に問題があれば既存ファイルを上書きしません。
374
374
 
375
- コマンドの使い方は [CLIコマンドリファレンス](../references/command-reference.md) の `schedule strategy(決定論的な strategy 生成)`、`approach` ごとの進め方は [実践の進め方ガイド](ryu-guide.md) を参照します。
375
+ コマンドの使い方は [[specdojo:command-reference|CLIコマンドリファレンス]] の `schedule strategy(決定論的な strategy 生成)`、`approach` ごとの進め方は [[specdojo:ryu-guide|実践の進め方ガイド]] を参照します。
376
+
377
+ ### 3.6. 人の文脈から始める `draft` profile
378
+
379
+ 人が前提や調査の委任範囲を雛形へ書いてから agent に下書きを任せたい場合は、`strategy-planning` の作業で対象成果物に `intent: draft-with-context` を宣言します。必要な Kata の保存済み grade がすべて `pass` なら `draft` profile を生成します。`not-needed` の型は不要として扱い、grade 不明・型の不足があれば生成を停止します。
380
+
381
+ ```yaml
382
+ approach_rules:
383
+ - local_ids: [prj-overview]
384
+ intent: draft-with-context
385
+ ```
386
+
387
+ | 段 | phase set | suffix | execution | mode | approach |
388
+ | ------------------ | --------------- | ------ | --------- | -------- | -------------- |
389
+ | 雛形作成・文脈記入 | `context-pass` | `010` | `human` | `edit` | `draft` |
390
+ | 下書き | `guided-pass` | `020` | `agent` | `edit` | `draft` |
391
+ | 磨き込み | `refine-pass` | `070` | `agent` | `edit` | `fully-guided` |
392
+ | 完成版レビュー | `review-pass` | `090` | `agent` | `review` | `fully-guided` |
393
+ | 確定 | `finalize-pass` | `140` | `human` | `edit` | `finalize` |
394
+
395
+ 雛形作成と文脈記入は一つの human 段にまとめます。雛形を人が確認してその場で文脈を記入でき、独立した空の待ち段を増やさずに draft へ渡せます。各段は直前の段に依存し、human の完了前に agent は着手しません。human 段には agent pipeline を付けません。
396
+
397
+ 1. `specdojo exec claim --project <project-id> --task <context-task-id> --by <human>` で着手します。既存の human タスクと同じく plan は生成せず、claim が作成した result に作業案内と記録欄を持ちます。
398
+ 2. `specdojo deliverable scaffold --project <project-id> --target <doc-id>` で対象成果物の雛形を作成します。既存成果物は上書きせず、`--force` は指定しません。
399
+ 3. 対象本文の `_CONTEXT_:` に固定前提・制約・調査や選定を任せる範囲を書きます。例: `_CONTEXT_: 既存 API を維持し、認証方式の候補を調べて提案してほしい。` 記法は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] の「文脈の目印」に従います。
400
+ 4. result に対象と記入内容を残し、`specdojo exec complete --project <project-id> --task <context-task-id> --by <human>` で draft へ渡します。draft は指示を本文へ反映し、元の指示と反映箇所を実行記録へ残します。続いて refine・review を行い、最後に人が finalize を claim / complete して確定します。
401
+
402
+ 文脈の記入を待つ必要がない場合は従来の `author-deliverable` を使います。必要な型がそろった場合の `fully-guided` profile も、草案作成の `guided-pass` は `approach: draft` です。文脈や成果物が未作成でも template を骨組みにして根拠のある範囲を下書きします。文脈が無いことを調査・選定の委任とは解釈せず、未委任の判断は保留します。既存 strategy の段定義を更新するには `schedule strategy generate --force` の差分を確認して適用し、構造が変わる場合は `schedule build --force`、続いて `exec refresh` を実行します。
376
403
 
377
404
  ## 4. タスク設計の品質
378
405
 
@@ -62,8 +62,16 @@ specdojo exec run --project <project-id> --auto --loop --parallel 5
62
62
 
63
63
  # FIFO順で実行する
64
64
  specdojo exec run --project <project-id> --auto --strategy fifo
65
+
66
+ # 指定した track だけから最大 3 件を選ぶ(実行前の確認)
67
+ specdojo exec run --project <project-id> --auto --track data-flow-uc-rewrite --parallel 3 --dry-run
68
+
69
+ # 同じ track の Ready がなくなるまで連続実行する
70
+ specdojo exec run --project <project-id> --auto --track data-flow-uc-rewrite --parallel 3 --loop
65
71
  ```
66
72
 
73
+ `--track <track>` は自動選択を 1 つの track に限定します。`sch-track-<track>.yaml`(または `.yml`)の track 名を大文字・小文字を区別して指定します。戦略による順序は維持され、準備や実行に失敗した後、`--loop` で枠を補充するときも、ほかの track は選びません。対象 track に Ready がなければ正常終了し、存在しない track は claim 前にエラーになります。`--track` は単一指定で `--auto` が必須です。省略時は従来どおり全 track から選びます。依存関係や Ready の計算は引き続きプロジェクト全体で行います。
74
+
67
75
  ### 1.2. auto実行中の注意点
68
76
 
69
77
  `--auto` と `--loop` は root の現在ブランチへ task ごとの merge commit を繰り返します(checkpoint commit は exec branch 側に置き、root には plan / result / claim event の複製が未commitのまま残ります)。同じ作業ツリーで並行して手作業を行う場合は、次の安全ガードに注意します。
@@ -142,6 +150,12 @@ specdojo exec plan --project <project-id> --task <task-id>
142
150
  specdojo exec run --project <project-id> --plan <execution-path>/exec/plans/<task-id>-plan.md
143
151
  ```
144
152
 
153
+ schedule のタスクから plan を生成するときは、Prettier による整形・ファイルへの書き込みより前に、phase の `description` を展開した plan 全体を markdownlint で検査します。箇条書きの前に空行がない場合(MD032)などは、タスク ID・plan のパス・生成内容の行番号・規則名を表示して停止し、既存の plan は上書きしません。表示する行番号は strategy YAML ではなく、整形前の plan に対する番号です。strategy の説明を修正し、`schedule build --track <track> --force` でトラックを更新してから plan を再生成してください。
154
+
155
+ 検査には利用リポジトリの markdownlint を優先し、見つからなければ SpecDojo 側のインストールを使います。どちらにもない場合は生成を停止するため、利用リポジトリで `npm install --save-dev markdownlint-cli` を実行してください。規則はリポジトリ直下の `.markdownlint.jsonc` / `.markdownlint.json` / `.markdownlint.yaml` / `.markdownlint.yml`(この順で最初にあるもの)と、上位ディレクトリを含む `.markdownlintrc` を読み、`extends` も解決します。設定がない場合は SpecDojo の標準規則を使います。CLI2 固有の設定や hook の独自ルールはこの検査の対象外です。生成履歴が `.markdownlintignore` に含まれていても、生成時の検査は行います。
156
+
157
+ 同じ検査は `exec run --auto` の plan 生成でも働き、`exec run --auto --dry-run` でも claim・checkpoint commit・agent 起動より前に Markdown の違反を検出できます。`exec run --task <task-id> --dry-run` のように plan を生成しない経路では検査しないため、事前確認には `exec plan --task <task-id>` を使ってください。
158
+
145
159
  schedule に無い成果物を catalog から直接 plan 化する場合は `--deliverable <local_id>` を使います。
146
160
 
147
161
  ```bash