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
@@ -253,6 +253,8 @@ specdojo register close \
253
253
 
254
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 は行いません。
255
255
 
256
+ ほかのファイルがすでに stage されていても、初回 commit と hook 整形後の amend は対象パスだけを記録し、既存の staged 変更を保持します。stage 後の検査や commit・amend が失敗した場合は、そのコマンドが stage した対象だけを unstage し、作業ツリーの本文を残します。amend の失敗時は初回 commit も残るため、本文と HEAD の差分を確認してから再実行してください。
257
+
256
258
  別 project への起票では、対象登録簿全体が clean であることを追加で確認します。元の作業ツリーのブランチと HEAD は変更しません。
257
259
 
258
260
  ### 2.2. 個票の作成
@@ -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.local_folder`)が一致するコンテナだけを探して接続し、停止していれば `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'
@@ -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