specdojo 0.4.0 → 0.4.2
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.
- package/.github/agents/specdojo-orchestrator.md +61 -2
- package/CHANGELOG.md +65 -0
- package/README.md +8 -7
- package/dist/commands/init.js +88 -15
- package/dist/commands/night-orchestrator.js +287 -0
- package/dist/commands/orchestrator.js +10 -3
- package/dist/dashboard/timeline-build.js +4 -151
- package/dist/devcontainer/command.js +3 -1
- package/dist/devcontainer/scaffold.js +166 -5
- package/dist/exec/agent-config.js +60 -2
- package/dist/exec/events.js +17 -6
- package/dist/exec/parent-validation.js +14 -0
- package/dist/exec/pipeline-state.js +13 -0
- package/dist/exec/plans-core.js +16 -5
- package/dist/exec/plans-storage.js +11 -3
- package/dist/exec/register.js +23 -1
- package/dist/exec/repo-integration.js +1 -1
- package/dist/exec/reporter.js +113 -13
- package/dist/exec/results.js +36 -14
- package/dist/exec/run/agent-pipeline.js +3 -0
- package/dist/exec/run/agent.js +40 -5
- package/dist/exec/run/job.js +2 -2
- package/dist/exec/run/lifecycle-commands.js +2 -2
- package/dist/exec/run/register-command.js +23 -4
- package/dist/exec/run/register-core.js +17 -0
- package/dist/exec/run/register-mode.js +39 -16
- package/dist/exec/run/register-post-review.js +420 -0
- package/dist/exec/run/register-resume.js +27 -11
- package/dist/exec/run/register-worktree.js +66 -2
- package/dist/exec/run/run.js +1 -1
- package/dist/exec/run/shared.js +22 -24
- package/dist/exec/task-repos.js +102 -15
- package/dist/kata/kata.js +1 -1
- package/dist/register/core.js +17 -4
- package/dist/register/create-commands.js +62 -6
- package/dist/register/cross-project.js +134 -0
- package/dist/register/derivation.js +28 -7
- package/dist/register/event-merge.js +13 -1
- package/dist/register/events.js +4 -0
- package/dist/register/item.js +35 -5
- package/dist/register/migration.js +1 -0
- package/dist/register/register.js +47 -30
- package/dist/schedule/strategy-generate-scope.js +2 -1
- package/dist/shared/catalog-files.js +31 -0
- package/dist/shared/git.js +45 -15
- package/dist/shared/lefthook-scaffold.js +177 -0
- package/dist/shared/provider-scaffold.js +3 -2
- package/dist/shared/specdojo-config.js +87 -17
- package/dist/shared/text.js +4 -1
- package/dist/shared/timeline-index.js +125 -0
- package/dist/shared/workspace-scaffold.js +69 -0
- package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +2 -1
- package/docs/ja/specdojo/exec-templates/xep-register-template.md +2 -0
- package/docs/ja/specdojo/exec-templates/xrp-register-post-run-template.md +46 -0
- package/docs/ja/specdojo/guides/branch-workflow-guide.md +34 -1
- package/docs/ja/specdojo/guides/docs-structure-guide.md +2 -0
- package/docs/ja/specdojo/guides/exec-config-guide.md +79 -11
- package/docs/ja/specdojo/guides/exec-operation-guide.md +39 -1
- package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +9 -3
- package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +4 -2
- package/docs/ja/specdojo/guides/quick-start-guide.md +31 -6
- package/docs/ja/specdojo/guides/register-operation-guide.md +54 -0
- package/docs/ja/specdojo/guides/remote-host-development-guide.md +52 -6
- package/docs/ja/specdojo/guides/specdojo-overview-guide.md +1 -1
- package/docs/ja/specdojo/guides/waza-guide.md +1 -1
- package/docs/ja/specdojo/references/command-reference.md +138 -64
- package/docs/ja/specdojo/references/specdojo-config-reference.md +41 -12
- package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +5 -2
- package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +92 -18
- package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +6 -1
- package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +12 -0
- package/docs/specdojo/schemas/v1/register-events.schema.yaml +2 -0
- package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +21 -0
- package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +40 -0
- package/package.json +17 -17
- package/templates/antigravity/README.md +1 -1
- package/templates/antigravity/orchestrator.md +61 -2
- package/templates/claude/agents/specdojo-orchestrator.md +61 -2
- package/templates/codex/README.md +17 -0
- package/templates/codex/agents/specdojo-orchestrator.toml +61 -2
- package/templates/codex/orchestrator.md +61 -2
- package/templates/devcontainer/devcontainer.json +3 -0
- package/templates/devcontainer/post-create.sh +15 -7
- package/templates/devcontainer/remote-host/specdojo-tmux.sh.sample +38 -5
- package/templates/devcontainer/remote-host/ssh-config.sample +3 -0
- package/templates/devcontainer/vim/vimrc +37 -0
- package/templates/init-agent-members.yaml +6 -6
- package/templates/init-exec-defaults.yaml +20 -1
- package/templates/lefthook/tools/install-lefthook.mjs +46 -0
- package/templates/lefthook/tools/specdojo-pre-commit.mjs +207 -0
- package/templates/opencode/README.md +6 -1
- package/templates/opencode/agents/specdojo-orchestrator.md +62 -3
- /package/dist/{shared → kata}/yaml-schema-modeline.js +0 -0
|
@@ -340,7 +340,40 @@ git push origin --delete feature/branch-policy
|
|
|
340
340
|
|
|
341
341
|
レビュー中または共同作業中の branch は無理に改名せず、完了後に新しい命名へ切り替える方が安全です。
|
|
342
342
|
|
|
343
|
-
## 10.
|
|
343
|
+
## 10. プロダクトリポジトリの統合先を指定する
|
|
344
|
+
|
|
345
|
+
別リポジトリ構成では、SpecDojo はプロダクトリポジトリにブランチ戦略を求めません。求めるのは、プロダクト側のルール(GitHub flow・git flow など)で決めた統合先を `repos[].integration_branch` に指定することだけで、ブランチ名に project ID を入れる必要はありません。`main` への取り込み方と merge の方式は、プロダクト側のルールに任せます。
|
|
346
|
+
|
|
347
|
+
### 10.1. GitHub flow と git flow での `integration_branch` の選び方
|
|
348
|
+
|
|
349
|
+
| プロダクト側の運用 | `repos[].integration_branch` の指定例 | 解説 |
|
|
350
|
+
| ------------------ | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
351
|
+
| GitHub flow | トピックのブランチ名(例: `feature/<topic>`) | トピックのブランチから統合先へ統合し、最終的に `main` へは PR で取り込む。トピックごとに書き換える場合もある |
|
|
352
|
+
| git flow | `develop` | feature を `develop` に統合し、`develop` から `main` へ release する。既存の `project/<id>/develop` の仕組みと同じ型で動く |
|
|
353
|
+
|
|
354
|
+
GitHub flow で register の worktree 実行ごとにトピックを変える場合は、`exec run --integration-branch <repo>=<branch>` で設定ファイルを書き換えずに統合先を指定できます。指定がない場合は `repos[].integration_branch`、それも省略した場合はそのリポジトリの現在のブランチを使います。
|
|
355
|
+
|
|
356
|
+
### 10.2. merge の方式ごとの `Refs:` の残り方
|
|
357
|
+
|
|
358
|
+
プロダクト側の exec branch 上の commit と merge commit には trace key `Refs: <project-id>:<item-id>` が付きます。merge の方式ごとに、この `Refs:` と記録した SHA の残り方が次のとおりです。
|
|
359
|
+
|
|
360
|
+
| merge の方式 | `Refs:`(プロダクト → プロジェクト) | 記録した SHA(プロジェクト → プロダクト) |
|
|
361
|
+
| ------------ | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
|
|
362
|
+
| merge commit | 残る | 統合先の祖先として残る |
|
|
363
|
+
| rebase merge | exec branch 上の commit の `Refs:` は残る。runner の merge commit は直線化で落ちる | SHA が変わると先祖ではなくなる |
|
|
364
|
+
| squash merge | GitHub の設定次第。「Pull request title」だけでは消え、「Pull request title and commit details」なら残る | 統合先の祖先ではなくなる。GitHub では PR の参照から辿れる |
|
|
365
|
+
|
|
366
|
+
squash merge を使う場合は、squash の commit メッセージに `Refs:` の行を残す設定(GitHub で「Pull request title and commit details」を選ぶなど)にします。`Refs: <project-id>:<item-id>` が消えると追跡が切れるためです。
|
|
367
|
+
|
|
368
|
+
### 10.3. 追跡を trace key で行う
|
|
369
|
+
|
|
370
|
+
追跡は SHA ではなく trace key(`Refs: <project-id>:<item-id>`)を主にします。`git log --grep` で辿れます。
|
|
371
|
+
|
|
372
|
+
```bash
|
|
373
|
+
git log --grep "Refs: <project-id>:<item-id>" --oneline
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
## 11. 作業前後のチェックリスト
|
|
344
377
|
|
|
345
378
|
| 時点 | 確認内容 |
|
|
346
379
|
| -------------------- | -------------------------------------------------------------------- |
|
|
@@ -375,6 +375,8 @@ app1-workspace/
|
|
|
375
375
|
|
|
376
376
|
`.specdojo/specdojo.config.json` の project パスは `app1-specdojo/` を基準とします。`config init` はリポジトリのディレクトリ名から `run.worktree_base` を作るため、この例では `../app1-specdojo-worktrees` になります。SpecDojo CLI の実行、プロジェクト成果物の解決、doc index の生成、運用記録の検証は `app1-specdojo/` 側で行います。
|
|
377
377
|
|
|
378
|
+
VS Code でプロジェクトリポジトリとプロダクトリポジトリを同時に開く場合は、`specdojo config scaffold --workspace` を実行して `<project-id>.code-workspace` を作成します。ワークスペースにはプロジェクトリポジトリ自身(`.`)と宣言した各プロダクトリポジトリ(`repos[].path`)が含まれ、worktree や隣接するリポジトリをシームレスに操作できます。
|
|
379
|
+
|
|
378
380
|
### 10.3. プロダクト文書の配置
|
|
379
381
|
|
|
380
382
|
プロダクト文書は実装と同期して改訂するため、`app1/docs/ja/product/` に置きます。README、ソースコードから生成する API リファレンス、パッケージ利用者向けの手順など、コードと同じ revision で読む付属文書も `app1/` に置きます。
|
|
@@ -35,12 +35,12 @@ SpecDojo のエージェント実行は、`sch-strategy-<track>.yaml` の phase
|
|
|
35
35
|
|
|
36
36
|
## 1. 設定ファイルの分担
|
|
37
37
|
|
|
38
|
-
| ファイル | 役割
|
|
39
|
-
| ------------------------------ |
|
|
40
|
-
| `sch-strategy-<track>.yaml` | phase ごとの `mode`・`approach`・実行要件・任意の `agent` / `agent_pipeline`
|
|
41
|
-
| `pm-members.yaml` | 人間の identity・連絡先・対応 Role code
|
|
42
|
-
| `.specdojo/agent-members.yaml` | agent の identity・capabilities・proficiency・priority・任意の `stage_role`
|
|
43
|
-
| `.specdojo/exec-defaults.yaml` | provider
|
|
38
|
+
| ファイル | 役割 | 粒度 |
|
|
39
|
+
| ------------------------------ | ------------------------------------------------------------------------------ | ------------ |
|
|
40
|
+
| `sch-strategy-<track>.yaml` | phase ごとの `mode`・`approach`・実行要件・任意の `agent` / `agent_pipeline` | トラック |
|
|
41
|
+
| `pm-members.yaml` | 人間の identity・連絡先・対応 Role code | プロジェクト |
|
|
42
|
+
| `.specdojo/agent-members.yaml` | agent の identity・capabilities・proficiency・priority・任意の `stage_role` | リポジトリ |
|
|
43
|
+
| `.specdojo/exec-defaults.yaml` | 難易度別の振り分け・provider 別起動コマンド・rate limit ポリシー・同時実行上限 | システム |
|
|
44
44
|
|
|
45
45
|
`sch-strategy` は通常、phase に「どんな能力が必要か」を書き、`.specdojo/agent-members.yaml` の候補から自動選択します。provider の利用枠を計画する phase だけは `agent` で個体を指名できます。
|
|
46
46
|
|
|
@@ -211,6 +211,11 @@ rate_limit_detection:
|
|
|
211
211
|
- "rate limit"
|
|
212
212
|
- "429"
|
|
213
213
|
|
|
214
|
+
# provider API へ接続できない場合の文言は provider ごとの設定を推奨
|
|
215
|
+
connection_error_detection:
|
|
216
|
+
stderr_patterns:
|
|
217
|
+
- "ECONNREFUSED"
|
|
218
|
+
|
|
214
219
|
rate_limit_policy:
|
|
215
220
|
cooldown_seconds:
|
|
216
221
|
rate_limit: 900
|
|
@@ -231,14 +236,74 @@ rate_limit_policy:
|
|
|
231
236
|
on_exhausted: block
|
|
232
237
|
```
|
|
233
238
|
|
|
239
|
+
複数 project が同じ `exec-defaults.yaml` を参照し、一部の project だけに親検証を足す場合は、`.specdojo/specdojo.config.json` の `projects.<id>.run.parent_validations` を使います。この配列は共有 defaults の `pipeline.parent_validations` を置き換えず、その後ろへ指定順に追加されます。
|
|
240
|
+
|
|
241
|
+
```json
|
|
242
|
+
{
|
|
243
|
+
"projects": {
|
|
244
|
+
"prj-0001": {
|
|
245
|
+
"run": { "exec_defaults": ".specdojo/exec-defaults.yaml" }
|
|
246
|
+
},
|
|
247
|
+
"prj-0002": {
|
|
248
|
+
"repos": [{ "name": "specdojo-lp", "path": "../specdojo-lp" }],
|
|
249
|
+
"run": {
|
|
250
|
+
"exec_defaults": ".specdojo/exec-defaults.yaml",
|
|
251
|
+
"parent_validations": [
|
|
252
|
+
{ "id": "typecheck", "repo": "specdojo-lp" },
|
|
253
|
+
{ "id": "lint-ts", "repo": "specdojo-lp" }
|
|
254
|
+
]
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
}
|
|
258
|
+
}
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
この例では共有 defaults の検証は両 project に適用され、`specdojo-lp` の 2 件は `prj-0002` の run だけに適用されます。`prj-0001` は `specdojo-lp` を `repos` に持たなくても影響を受けません。共有側と project 側に同じ ID・同じ `repo` の組を書くと、合成後の重複として agent 起動前にエラーになります。project 固有の検証も親 runner が固定 argv で実行し、evidence には `source: runner` と実行先の `repo` が記録されます。
|
|
262
|
+
|
|
234
263
|
`wait` の待機中は、同一 worktree と register / pipeline の状態を別 run から保護するため project の実行ロックを保持します。register worktree の `--join` 実行は共有枠の範囲で引き続き動作できます。wait / fallback の再開時刻と切替元・切替先は pipeline state と executor evidence に記録されます。
|
|
235
264
|
|
|
236
|
-
|
|
265
|
+
### 5.1. register の難易度別振り分け
|
|
266
|
+
|
|
267
|
+
`routing` は、個票の `difficulty`(`hard` / `medium` / `easy`)ごとに register pipeline の executor・reporter と、指名した agent が rate limit になったときの扱いを定義します。
|
|
268
|
+
|
|
269
|
+
```yaml
|
|
270
|
+
routing:
|
|
271
|
+
hard:
|
|
272
|
+
executor_by: sol-executor
|
|
273
|
+
reporter_by: gemma26-reporter
|
|
274
|
+
on_rate_limit: wait
|
|
275
|
+
fallback_executor_by: opus-executor
|
|
276
|
+
fallback_reporter_by: sonnet-reporter
|
|
277
|
+
medium:
|
|
278
|
+
executor_by: flash-high-executor
|
|
279
|
+
reporter_by: gemma26-reporter
|
|
280
|
+
on_rate_limit: fallback
|
|
281
|
+
fallback_executor_by: sol-executor
|
|
282
|
+
fallback_reporter_by: sonnet-reporter
|
|
283
|
+
easy:
|
|
284
|
+
executor_by: qwen-executor
|
|
285
|
+
reporter_by: gemma26-reporter
|
|
286
|
+
on_rate_limit: fallback
|
|
287
|
+
fallback_executor_by: flash-high-executor
|
|
288
|
+
fallback_reporter_by: sonnet-reporter
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
`exec run --register` は個票に `difficulty` があり、対応する表がある場合だけこの指定を使います。個票に難易度がない場合、または対応する表がない場合は、`stage_role` と `priority` による従来の自動選択へ戻ります。CLI の `--executor-by`・`--reporter-by`・`--on-rate-limit`・fallback 指定は、指定した項目だけ表より優先します。`on_rate_limit: wait` でも fallback は接続不能時の切替先として使用されます。
|
|
292
|
+
|
|
293
|
+
上の `qwen-executor` を使う `easy` の例は、変更範囲が docs・src・tests の内側で完結し、それらの外を変更しない作業に限る運用を前提にしています。難易度は優先度ではなく、必要な推論・判断と安全な変更範囲から決めます。
|
|
294
|
+
|
|
295
|
+
`specdojo init --exec` は、選択した provider の member に合わせて 3 段階の表を生成します。provider を複数選んだ場合は、後続 provider の executor / reporter を fallback の例にも使います。
|
|
296
|
+
|
|
297
|
+
`connection_error_detection` は、provider API やローカル LLM へ接続できない失敗を `rate_limit_detection` と同じ終了コード・出力パターンの仕組みで検出します。`--fallback-executor-by` / `--fallback-reporter-by` または `rate_limit_policy.pinned` の対応する fallback があれば、`--on-rate-limit` の値とは独立して代替 agent へ1回だけ切り替えます。fallback が無い場合は通常の agent 失敗として停止します。接続エラーでは同じ agent の `wait` は行いません。切替原因は pipeline state・executor evidence・result に記録されます。文言は provider ごとに異なるため、`providers.<provider>.connection_error_detection` へ置くことを推奨します。
|
|
298
|
+
|
|
299
|
+
`test-integration` は組み込み許可リストで `npm run test:integration` へ解決されます。設定や executor evidence に command・引数を書くことはできません。未知 ID、重複 ID は agent 起動前の設定エラーになります。親 runner は `shell: false` の固定 argv で実行し、現時点で許可される ID は `validate-schema`、`typecheck`、`test-unit`、`test-integration`、`lint-ts`、`lint-fm`、`lint-md`、`build`、`format-check` の 9 つです。
|
|
237
300
|
|
|
238
301
|
`typecheck`(`npm run typecheck`)は Vitest と異なり型検査を行うため、executor が残した TypeScript の型エラーを検出します。Vitest は型検査を行わないため、`typecheck` を親検証に含めないと型エラーは test-unit を通過して統合時の pre-commit hook で初めて失敗するため、既定では `test-unit` の前に置いて早めに止めます(PJR-W66B)。
|
|
239
302
|
|
|
240
303
|
`lint-ts`(`npm run lint:ts`)、`lint-fm`(`npm run lint:fm`)、`lint-md`(`npm run lint:md`)は、executor が残した ESLint・frontmatter・Markdown の lint エラーを agent の段階で検出します。指定しない場合、これらのエラーは統合後の `npm run check` まで持ち越されます(PJR-K1Z5)。
|
|
241
304
|
|
|
305
|
+
`build`(`npm run build`)と `format-check`(`npm run format:check`)は、別リポジトリ構成でプロダクトリポジトリのビルド確認とコード整形確認を親 runner で実行するために使います。agent の sandbox 内で npm を実行できない環境でも、統合前にビルドと整形の検査を自動化できます(PJR-NS8Y)。
|
|
306
|
+
|
|
242
307
|
`specdojo.config.json` の project に `repos` を宣言した別リポジトリ構成では、`pipeline.parent_validations` の要素に `{ id, repo }` を書き、検証を実行するリポジトリを割り当てられます(PJR-V96B)。ID だけの要素はプロジェクトリポジトリで実行します。`repo` には、プロジェクトリポジトリを表す `project` か、`repos` で宣言したプロダクトリポジトリの名前を書きます。
|
|
243
308
|
|
|
244
309
|
```yaml
|
|
@@ -253,7 +318,7 @@ pipeline:
|
|
|
253
318
|
|
|
254
319
|
- 親 runner は、割り当てたリポジトリの task worktree(`<worktree_base>/<task-id>/<repo>/`)を `cwd` にして検証を実行します。そのリポジトリに変更が無くても省略しません。統合先の破損を検出するためです。
|
|
255
320
|
- evidence の runner 検証には `repo` を記録します。記録するのは、task がプロダクトリポジトリを持つ場合か、要素が `{ id, repo }` の場合です。`repos` を持たない project で ID だけを書いた場合、evidence と実行場所は従来と同じです。
|
|
256
|
-
- executor がプロダクトリポジトリの検証を `not_run`
|
|
321
|
+
- executor がプロダクトリポジトリの検証を `not_run` または `not_applicable` として報告するときは、`npm --prefix <repo> run <script>`、`<repo>:<path>`、または `$SPECDOJO_REPO_<NAME>` / `${SPECDOJO_REPO_<NAME>}` のように対象リポジトリをコマンドへ含めます。runner はコマンドとリポジトリの組で照合し、同じリポジトリに割り当てた同一コマンドの親検証が成功した場合だけ、executor の報告を無視して親検証を正とします。別のプロダクトリポジトリや project リポジトリでの成功は代用しません。
|
|
257
322
|
- ログと block 理由では、プロダクトリポジトリの検証を `<repo>:<id>`(例: `app2:test-unit`)と表示します。
|
|
258
323
|
- task の worktree が無いリポジトリへ割り当てた検証は、コマンドを起動せずに `failed` になります。`repos` に無い名前を書いた場合も同じです。
|
|
259
324
|
- 同じ `id` と `repo` の組の重複、`id`・`repo` 以外のキー、`repo` の無いオブジェクトは、agent 起動前の設定エラーになります。
|
|
@@ -261,6 +326,8 @@ pipeline:
|
|
|
261
326
|
|
|
262
327
|
`run.register_execution` は、`exec run --register` の既定の実行場所です。`worktree` または `in-place` を指定します。省略時は既存リポジトリとの互換性のため `in-place` です。CLI の `--worktree` / `--in-place` は設定を上書きし、同時指定はエラーになります。
|
|
263
328
|
|
|
329
|
+
`run.register_post_review` は、register の worktree 統合後に読み取り専用 review pipeline を実行し、todo / issue を verdict に応じて自動 close または `waiting` へ遷移するかを指定する boolean です。既定は `false` です。CLI の `--post-review` でもその run だけ有効にできます。review executor の既定は `claude-expert-review-executor` で、`--review-by` が優先されます。詳しい判定と、runner 自身を変更した項目を自動 close しない規則は [exec運用ガイド](exec-operation-guide.md) を参照してください。
|
|
330
|
+
|
|
264
331
|
`run.max_concurrent_runs` は、同じ project で同時に動かせる `exec run` プロセスの数の上限です。最初の run と、register の worktree 実行へ `--join` で合流する run の合計で数えます。正の整数だけを指定でき、省略時や不正な値の場合は `4` です。`1` を指定すると `--join` は無効になります。現在の使用数は `exec slots --project <project-id>` で確認できます。
|
|
265
332
|
|
|
266
333
|
`pipeline.parent_validation_concurrency` は、1 つの `exec run` プロセスの中で親検証を同時に実行できる項目数の上限です。正の整数だけを指定でき、省略時は `1` です。`--parallel` で複数項目を並行実行しても、親検証は項目単位で 1 本ずつ直列に実行されます。vitest は検証ごとに複数の worker を起動するため、検証が重なるとコンテナの負荷で成果物と無関係なタイムアウトが起きます。これを防ぐための既定値です(PJR-3HHW)。制限の対象は親検証だけで、executor と reporter は `--parallel` のとおり並行に動きます。空きを待つ項目は `Waiting for parent validation slot: <項目> (<検証 ID>); running: <実行中の項目>` をログへ出力し、枠を得たときに `Parent validation slot acquired: <項目>` を出力します。
|
|
@@ -272,6 +339,7 @@ provider ごとに挙動が異なる設定は `providers.<provider>` に置き
|
|
|
272
339
|
- `command_template`: その provider の agent を起動するコマンドテンプレート。`{nickname}`・`{model}`・`{mode}`・`{proficiency}` と `command_params` の変数を member 属性で展開します。`model` のない従来 member は、これまでどおり `command_params` の `model` を使用できます。グローバル既定は持ちません。
|
|
273
340
|
- `command_params`: テンプレートの追加変数表。`by_mode.<mode>`、`by_proficiency.<proficiency>`、`by_nickname.<nickname>` に変数名と値の組を置きます。同じ変数は `by_nickname`、`by_proficiency`、`by_mode` の順で優先します。
|
|
274
341
|
- `rate_limit_detection`: provider 固有の検出シグナル(`stderr_patterns` を優先します)。
|
|
342
|
+
- `connection_error_detection`: provider API やローカル LLM へ接続できない場合の検出シグナル(`stderr_patterns` を優先します)。
|
|
275
343
|
- `rate_limit_policy`: provider 固有のリトライ/フォールバック/block ポリシー。
|
|
276
344
|
- `rate_limit_policy.cooldown_seconds`: reset / retry-after が無い retryable signal にだけ使う明示的な延期秒数。未指定の kind は再開時刻を推定しません。
|
|
277
345
|
- `max_concurrency`: その provider の agent を 1 ラウンドで同時に走らせる上限(正の整数)。未指定・0 以下・非整数は「上限なし」として扱います。register の worktree 実行では、`--join` で合流した run を跨いで数えます。
|
|
@@ -455,9 +523,9 @@ executor の出力は、そのまま reporter へ渡さずに run 単位の evid
|
|
|
455
523
|
- 親検証は失敗時だけ出力を保存し、成功時は要約だけを記録します。失敗ログは `parent-validation-output` として `log_refs` から参照します。同じ run の resume や統合段の再検証では attempt 番号を増やして新しいログを追加し、以前の失敗ログを上書きしません。親検証の要約は 1,000 文字以内で先頭と末尾を残すため、末尾に出る失敗ケース名と件数を evidence から確認できます。
|
|
456
524
|
- evidence ディレクトリは Git の管理対象です。成功して統合された run のログは履歴に残り、失敗中の worktree では未コミットのまま保持されます。`--force-restart` などで worktree を破棄すると未コミットログも失われるため、必要な調査を先に行います。既知パターンは保存前に秘匿しますが、未知形式の秘密が残る可能性を考慮し、ログを外部共有する前に内容を確認します。
|
|
457
525
|
- executor が構造化した最終報告を返す場合は、標準出力に `<specdojo_executor_evidence>` タグで JSON(`final_message`・`validations`)を出します。`validations[].status` は `passed` / `failed` / `not_run` / `not_applicable` / `requires_human` のいずれかです。`not_applicable` はリポジトリが検査の適用条件を満たさない場合に使い、`reason` へ理由を必ず記録します。`requires_human` は、実 agent CLI の起動、利用枠や課金を伴う操作、認証情報やホスト側の操作など、agent の sandbox から実行できない確認だけに使います。実行できるが省略した検証には使わず、`not_run` として記録します。タグが無い場合は標準出力の残りを最終メッセージとして扱います。
|
|
458
|
-
- `pipeline.parent_validations` には `validate-schema`(`npm run validate:schema`)、`typecheck`(`npm run typecheck`)、`test-unit`(`npm run test:unit`)、`test-integration`(`npm run test:integration`)、`lint-ts`(`npm run lint:ts`)、`lint-fm`(`npm run lint:fm`)、`lint-md`(`npm run lint:md`)を指定できます。親 runner は executor の成功後・reporter の起動前に、指定順で固定 argv の検証を実行します。
|
|
459
|
-
- executor prompt には設定済み ID と対応コマンドを明示します。executor はそのコマンドや対象限定版を sandbox
|
|
460
|
-
- result の `changed_files` のパスは evidence の `changes` から、execution の evidence、project register とその派生ビュー、当該 result という runner 管理記録を除いて runner が機械生成します。除外後の変更一覧だけを reporter へ渡し、edit の変更説明は evidence のパスと対にして受け取ります。runner はパスで突き合わせるため、説明の順序は問いません。説明が不足したパスには Git の変更メタデータ(追加・変更・削除・名前の変更、行数)を記録し、変更ファイルが多い場合(50 件超)はディレクトリごとに集約して記録します。evidence にないパスの説明は捨てます。`outcome` と `block_reason` は stage の状態・終了コード・保護機構が保存した理由・executor / 親 runner の検証から機械生成します。reporter の JSON Schema は文章項目と対応づけ用のパスだけを受け付け、いずれかの検証が failed または `not_run` なら、reporter の文章にかかわらず機械判定は blocked です。ただし、executor が `not_run
|
|
526
|
+
- `pipeline.parent_validations` には `validate-schema`(`npm run validate:schema`)、`typecheck`(`npm run typecheck`)、`test-unit`(`npm run test:unit`)、`test-integration`(`npm run test:integration`)、`lint-ts`(`npm run lint:ts`)、`lint-fm`(`npm run lint:fm`)、`lint-md`(`npm run lint:md`)、`build`(`npm run build`)、`format-check`(`npm run format:check`)を指定できます。親 runner は executor の成功後・reporter の起動前に、指定順で固定 argv の検証を実行します。
|
|
527
|
+
- executor prompt には設定済み ID と対応コマンドを明示します。executor はそのコマンドや対象限定版を sandbox 内で実行せず、executor evidence の validations にも含めなくてよいものとします。親 runner の結果は `source: runner` と許可リスト `id` 付きで同じ `validations` 配列へ保存します。executor が同じ検査を `not_run` または `not_applicable` として含めた場合も、同じリポジトリで実行された親 runner の結果を正とします。これにより sandbox 内で成立しない検証を親へ移した場合も二重実行せず、executor の重複報告で run を止めません。
|
|
528
|
+
- result の `changed_files` のパスは evidence の `changes` から、execution の evidence、project register とその派生ビュー、当該 result という runner 管理記録を除いて runner が機械生成します。除外後の変更一覧だけを reporter へ渡し、edit の変更説明は evidence のパスと対にして受け取ります。runner はパスで突き合わせるため、説明の順序は問いません。説明が不足したパスには Git の変更メタデータ(追加・変更・削除・名前の変更、行数)を記録し、変更ファイルが多い場合(50 件超)はディレクトリごとに集約して記録します。evidence にないパスの説明は捨てます。`outcome` と `block_reason` は stage の状態・終了コード・保護機構が保存した理由・executor / 親 runner の検証から機械生成します。reporter の JSON Schema は文章項目と対応づけ用のパスだけを受け付け、いずれかの検証が failed または `not_run` なら、reporter の文章にかかわらず機械判定は blocked です。ただし、executor が `not_run` または `not_applicable` と記録したコマンドを、親 runner が同じリポジトリで同じコマンドとして実行し成功していれば、親 runner の結果を正として executor の報告を無視します。さらに、`npm run <name>` に対応する script がない、`npx <package>` の package が `dependencies` / `devDependencies` にない、検査の対象となる種類の変更ファイルがない、または SpecDojo サブコマンドの設定上の適用条件を満たさないことを runner が機械的に確定できる場合、その `not_run` は block せず、edit result の申し送りへ「適用外の検証(runner の判定)」として追記します。変更ファイル種別で判定する対応は共通規約の検査表を正本とし、`validate:schema:file` は `*.yaml` / `*.yml`、Prettier は `*.md` / `*.ts` / `*.js` / `*.json` / `*.yaml` / `*.yml`、markdownlint は `*.md` の変更がある場合だけ適用対象とします。rename は変更前後の両方を見て、プロダクトリポジトリのコマンドはそのリポジトリの変更だけで判定します。`typecheck` など、この対応に含まれない検査の判定は変更しません。SpecDojo の起動形は `specdojo <subcommand>`、`npx specdojo <subcommand>`、ソース/配布済み CLI の直接起動を認識し、`catalog validate` は対象 project の `catalog_path` で判定します。対象 project は、コマンドの `--project <id>`、run の対象 project(runner が execution path に一致する project を設定から特定したもの)、`current_project` の順に決めます。別の project が `catalog_path` を持っていても、run の対象 project に `catalog_path` がなければ適用外です。対象 project に `catalog_path` があっても、executor の変更(runner 管理記録を除き、rename は変更前後の両方を見ます)が `docs/ja/projects/` 配下に及ばない run では、plan の共通規約の検証表と同じく適用外とし、executor の `not_applicable` も受理します。変更が及ぶ run では従来どおり適用対象です。また、`<repo>:<path>` を引数に含むコマンド、`--prefix <repo>` 付きのコマンド、または `$SPECDOJO_REPO_<NAME>` / `${SPECDOJO_REPO_<NAME>}` を含むコマンドは、対象 project が `repos` で宣言したそのプロダクトリポジトリの `package.json` で script と依存を判定します(`--prefix` はリポジトリ名か設定の `path` と一致するものを対象にします)。設定が読めない、対象 project を特定できない、または適用条件を未定義のサブコマンドは機械的な救済をせず、通常の `not_run` として扱います。executor の failed は親 runner の成功や適用外判定で打ち消しません。`npm run check` のように npm script を `&&` でつないだだけの合成コマンドを executor が `not_run` とした場合は、対象リポジトリの `package.json` の script を展開し、構成する各コマンドが同じリポジトリの親検証か executor 自身の検証で通っていれば満たされたものとして扱います。`npm test` は、`npm run test:unit` と `npm run test:integration` の両方が通っていれば満たされたものとします。構成するコマンドの script の中身と同じコマンドを executor が直接実行して通した場合も満たします(`tsx` の起動の書き方の違いはそろえて比べます)。任意のシェルを含む script は展開しません。理由付きの `not_applicable` は block の理由にせず、runner が edit result の申し送りへ「適用外の検証: `<コマンド>`(<理由>)」として機械的に追記します。ただし、理由がない場合、変更ファイル種別を含む適用条件を満たした `npm run <name>` の script が存在する場合、または同条件を満たした `npx <package>` の package が `dependencies` / `devDependencies` に存在する場合は誤申告として blocked にします。SpecDojo サブコマンドは package の有無だけでは反証せず、既知の適用条件を設定から判定します。適用条件が未定義なら理由付きの agent の申告に従います。`specdojo index build`(`npx specdojo index build`・`node --import tsx src/specdojo.ts index build` などの起動形を含みます)は runner が担う検証です。出力先の `.specdojo/doc-index.json` は agent が書き込めず、index は worktree の準備と統合の前に runner が再生成するため、executor への指示では実行も記録もしないよう伝えます。executor が `not_run` / `not_applicable` と記録しても block の理由にせず、`not_run` の場合は edit result の申し送りへ「runner が担う検証: `<コマンド>`(<理由>)」として追記します。runner の再生成が失敗した場合は worktree の準備で run が止まるか、runner の検証の失敗として block するため、満たしたものとは扱いません。executor の failed は救済せず、ほかの SpecDojo サブコマンドの `not_run` の扱いも変えません。executor の `requires_human` は block の理由にせず、runner が edit result の申し送りへ「人の確認が必要: `<コマンド>`(<要約>)」として機械的に追記します。項目は review へ進み、人が確認してから close します。
|
|
461
529
|
- reporter の出力は JSON Schema で厳格に検証します。形式不正のときは同じ plan と evidence のまま reporter だけを最大 3 回再実行し、executor は再実行しません。
|
|
462
530
|
- reporter stage の再開では、現在の設定 ID と一致する親検証が保存済み evidence にそろっている場合だけ executor evidence を再利用します。`{ id, repo }` を使う場合は、ID とリポジトリの組が一致することを求めます。再実行時も同じ割り当てで、各リポジトリの worktree を `cwd` にします。保存済みの親検証がすべて成功していれば再実行しません。`failed` / `not_run` があれば、親 runner が現在の worktree で固定許可リストの親検証を再実行し、同じ ID の結果を evidence 上で置換してから reporter へ渡します。過去の親検証ログは置換せず、新しい失敗ログだけを追加します。executor 由来の検証は再実行・置換しません。設定 ID が変わった、または結果が欠けている場合、Schedule 実行は新しい executor run としてやり直し、register 実行は明示的な再実行を促して再開を拒否します。
|
|
463
531
|
- result の frontmatter は runner が scaffold した内容を保ち、本文は検証済みの reporter 文章と evidence 由来の事実を組み合わせて runner が描画します。reporter はファイルを書きません。
|
|
@@ -362,6 +362,8 @@ track の再生成では、`exec validate` の警告と同じ鮮度判定を使
|
|
|
362
362
|
|
|
363
363
|
provider別の `max_concurrency` や agent 選択は [exec設定ガイド](exec-config-guide.md) を参照します。
|
|
364
364
|
|
|
365
|
+
指名した executor / reporter が provider API やローカル LLM へ接続できず、`connection_error_detection` に一致した場合は、対応する fallback 指定があれば1回だけ切り替えます。この判定は `--on-rate-limit` とは独立しているため、rate limit を `stop` または `wait` にしていても接続不能時の fallback は働きます。fallback 未指定時は通常の失敗として停止します。
|
|
366
|
+
|
|
365
367
|
### 2.6. executor / reporter pipelineの実行と復旧
|
|
366
368
|
|
|
367
369
|
`agent_pipeline` を持つ phase のタスクは、executor(成果物の編集と検証)と reporter(evidence から result を構成)の 2 stage で実行されます。実行コマンドは従来と同じで、stage の agent を固定したい場合だけ `--executor-by` / `--reporter-by` を足します。
|
|
@@ -412,7 +414,38 @@ specdojo exec resume \
|
|
|
412
414
|
|
|
413
415
|
executor と reporter が成功した後の commit・merge・worktree 撤去で止まった場合、`exec resume --task <task-id>` は agent を起動せず、`pipeline-state.json` の `integrate` 段から統合だけを再開します。前回の merge が完了している場合は exec branch を再 merge せず、runner が残した lifecycle 差分を確認したうえで worktree 撤去と `exec complete` だけを行います。通常実行の成功時は `integrate.status=succeeded`、失敗時は `failed` と block event の `pipeline_state_ref` が残ります。
|
|
414
416
|
|
|
415
|
-
### 2.7. register
|
|
417
|
+
### 2.7. register統合後のreviewと自動close
|
|
418
|
+
|
|
419
|
+
register の worktree 実行では、`--post-review` を付けると、成果を統合した後に読み取り専用の review pipeline を実行できます。review executor の既定は `claude-expert-review-executor` で、`--review-by` により変更できます。reporter は `stage_role: reporter` の候補から選び、edit pipeline で `--reporter-by` を指定している場合は同じ reporter を使います。
|
|
420
|
+
|
|
421
|
+
```bash
|
|
422
|
+
specdojo exec run \
|
|
423
|
+
--project <project-id> \
|
|
424
|
+
--register <PJR-ID> \
|
|
425
|
+
--worktree \
|
|
426
|
+
--post-review
|
|
427
|
+
```
|
|
428
|
+
|
|
429
|
+
毎回有効にする場合は `.specdojo/exec-defaults.yaml` に設定します。既定は `false` です。post-review は統合後の差分を対象にするため、in-place 実行では利用できません。
|
|
430
|
+
|
|
431
|
+
```yaml
|
|
432
|
+
run:
|
|
433
|
+
register_execution: worktree
|
|
434
|
+
register_post_review: true
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
review executor は、個票の完了条件、edit plan/result、executor evidence の検証結果、統合 commit の差分を照合します。成果物や個票を変更すると runner が `incomplete` として扱います。runner は verdict と個票の種類から次の遷移を行い、review executor を actor、review result の判断根拠を reason として register event に残します。
|
|
438
|
+
|
|
439
|
+
| 個票の種類 | verdict | 遷移 |
|
|
440
|
+
| ------------ | ------------------------------------------- | ------------------------------------ |
|
|
441
|
+
| todo / issue | `complete` / `complete-with-findings` | `done` へ close |
|
|
442
|
+
| todo / issue | `incomplete` | `waiting` |
|
|
443
|
+
| その他 | `complete` / `complete-with-findings` | `review` のまま(自動 close しない) |
|
|
444
|
+
| すべて | `incomplete`、review 失敗、未対応の verdict | `waiting` |
|
|
445
|
+
|
|
446
|
+
SpecDojo package 自身の `src/`・`tools/`・`package.json`・lock file を変更した項目は、統合済みでも実行中の親プロセスが新しい runner コードを読み直せません。この場合、verdict が完了でも自動 close せず `review` に残します。新しいプロセスで実際の `exec run` を smoke test し、人が close してください。
|
|
447
|
+
|
|
448
|
+
### 2.8. register実行の再開
|
|
416
449
|
|
|
417
450
|
複数の register 項目を worktree で並列実行するときは、`--executor-by` に `PJR-ID=nickname` をカンマ区切りで渡すと、項目ごとに executor を固定できます。従来の `--executor-by <nickname>` は引き続き全項目への共通指定です。項目別指定は起動対象をすべて指定する必要があり、起動対象外の ID や指定漏れがあると、状態遷移や worktree 作成の前にエラーになります。`--dry-run` では各項目について解決した executor とコマンドを確認できます。
|
|
418
451
|
|
|
@@ -567,6 +600,7 @@ specdojo register add \
|
|
|
567
600
|
--type todo \
|
|
568
601
|
--title "SpecDojo 設定ガイドの改訂" \
|
|
569
602
|
--topic exec-config-guide-revision \
|
|
603
|
+
--difficulty medium \
|
|
570
604
|
--approach fully-guided \
|
|
571
605
|
--target specdojo:exec-config-guide \
|
|
572
606
|
--owner DEV
|
|
@@ -578,6 +612,7 @@ specdojo register add \
|
|
|
578
612
|
specdojo register update \
|
|
579
613
|
--project <project-id> \
|
|
580
614
|
--id <PJR-ID> \
|
|
615
|
+
--difficulty hard \
|
|
581
616
|
--approach fully-guided \
|
|
582
617
|
--target specdojo:exec-config-guide
|
|
583
618
|
```
|
|
@@ -595,6 +630,7 @@ specdojo:
|
|
|
595
630
|
item_type: todo
|
|
596
631
|
item_status: open
|
|
597
632
|
priority: medium
|
|
633
|
+
difficulty: medium
|
|
598
634
|
owner: DEV
|
|
599
635
|
approach: fully-guided
|
|
600
636
|
targets:
|
|
@@ -603,6 +639,8 @@ specdojo:
|
|
|
603
639
|
|
|
604
640
|
`approach` を指定した個票では、`targets` は **1 件だけ必須** です(schedule のタスクと同様に 1 件の成果物または 1 件の kata を対象にします)。
|
|
605
641
|
|
|
642
|
+
`difficulty` は `hard` / `medium` / `easy` のいずれかです。`exec run --register` と `orchestrator night` は、agent を CLI で指定していない段について `exec-defaults.yaml` の `routing` から executor・reporter・rate limit 対応を選びます。既存の個票で `difficulty` を省略した場合や表がない場合は、従来どおり agent 名簿の `priority` 順で自動選択します。CLI の指定は表より優先します。
|
|
643
|
+
|
|
606
644
|
### 4.3. 対象の指定方法と kata 保守 approach の選び方
|
|
607
645
|
|
|
608
646
|
`targets` に指定する対象文書の書き方と、kata 保守の進め方(`approach`)の選び方は次のとおりです。
|
|
@@ -58,13 +58,17 @@ CLI を直接操作する場合の代表フローは [遂行の技活用ガイ
|
|
|
58
58
|
| `orch:qwen:work` | OpenCode / Qwen 3.8 | `../worktrees/qwen-work`(無ければ自動作成) |
|
|
59
59
|
| `orch:gemma` | OpenCode / Gemma 4 | なし |
|
|
60
60
|
| `orch:gemma:work` | OpenCode / Gemma 4 | `../worktrees/gemma-work`(無ければ自動作成) |
|
|
61
|
-
| `orch:
|
|
62
|
-
| `orch:
|
|
61
|
+
| `orch:flash` | Antigravity / `gemini-3.8-flash-high` | なし |
|
|
62
|
+
| `orch:flash:work` | Antigravity / `gemini-3.8-flash-high` | `../worktrees/agy-work`(無ければ自動作成) |
|
|
63
63
|
|
|
64
64
|
Antigravity CLI(`agy`)はファイル定義の agent を持たないため、Codex と同じく SSOT `.agents/specdojo-orchestrator.agent.md` の本文を `-i`(初期プロンプトを与えて対話を続ける)で渡します。ラッパーは不要で、`.agents/rules/*.md` の薄いラッパー経由で `.github/instructions/` の規則も読み込まれます。
|
|
65
65
|
|
|
66
66
|
Antigravity で使えるモデル ID は `agy models` で確認してください。配布時点の既定値は、agy 1.3.5 で提供される `gemini-3.8-flash-high` です。
|
|
67
67
|
|
|
68
|
+
`specdojo init` と `config scaffold` が利用者の `package.json` へ追加するスクリプトは、Claude Code が `orch:opus`・`orch:sonnet`、Codex が `orch:sol`・`orch:terra`、Antigravity が `orch:flash`、OpenCode が `orch:opencode` です。Codex と Antigravity のスクリプトは、名前に対応するモデルを起動コマンドで明示します。
|
|
69
|
+
|
|
70
|
+
0.4.0 以前に作った `orch:codex`・`orch:agy` は自動では削除・上書きされません。`config scaffold --provider codex` または `config scaffold --provider antigravity` を再実行して新しいスクリプトを追加し、新しい名前で起動できることを確認してから、旧スクリプトを `package.json` から削除してください。
|
|
71
|
+
|
|
68
72
|
用途に応じて使い分けます。
|
|
69
73
|
|
|
70
74
|
```bash
|
|
@@ -80,7 +84,9 @@ npm run orch:sonnet:work
|
|
|
80
84
|
|
|
81
85
|
frontier モデルは Claude Code が `opus`、Codex が `gpt-5.6-sol` に対応します。通常運用はそれぞれ既定の `sonnet` / `gpt-5.6-terra` を使います。
|
|
82
86
|
|
|
83
|
-
worktree 付きは、全 CLI で `tools/worktree/open-agent-worktree.sh` を通して固定名の worktree
|
|
87
|
+
worktree 付きは、全 CLI で `tools/worktree/open-agent-worktree.sh` を通して固定名の worktree を使い、そこから `specdojo orchestrator launch` を起動します。無ければ起動時に作成します。ブランチは `worktree/<name>`、配置は `../worktrees/<name>` です。既存 worktree のブランチが一致しない場合は agent を起動しません。Claude Code の `--worktree` はブランチ名と配置を他の CLI に揃えられないため使用しません。
|
|
88
|
+
|
|
89
|
+
固定 worktree から起動しても、project 設定と `repos[].path` は主 worktree を基準に解決します。provider の作業ディレクトリは固定 worktree のままです。この受け渡しに使う内部用の `SPECDOJO_ORCHESTRATOR_CONFIG_ROOT` は provider 起動前に除去されるため、対話中に実行する別の `specdojo` コマンドへは引き継がれません。
|
|
84
90
|
|
|
85
91
|
### 2.1. 利用リポジトリへ設定を配置する
|
|
86
92
|
|
|
@@ -94,6 +94,8 @@ exec/results/<stem>-result.md
|
|
|
94
94
|
2. `--task <task-id>` がある場合は、`<stem> = <task-id>` とします。
|
|
95
95
|
3. task identity がない場合は、`<slug>-<UTC>-<rand>` のユニーク名を採番します。
|
|
96
96
|
|
|
97
|
+
`<rand>` は4バイト(16進8桁)です。同じプロセス内で slug・UTC秒・乱数がすべて重複した場合は、`<rand>-1`、`<rand>-2` のように連番を加えます。plan path から stem を読む処理は stem 全体を連結キーとして扱うため、従来の16進4桁の名前と連番付きの名前をどちらも読み取れます。
|
|
98
|
+
|
|
97
99
|
これにより、task 実行は固定名で扱い、schedule 非依存の実行は実行ごとの証跡を残せます。
|
|
98
100
|
|
|
99
101
|
### 2.4. deliverable指定の解決
|
|
@@ -199,10 +201,10 @@ specdojo exec archive --project <project-id> --task <task-id>
|
|
|
199
201
|
| 軽量実行(状態追跡なし) | `exec archive` で明示的に移動する |
|
|
200
202
|
| `exec run --archive-on-success` | 成功時に移動する |
|
|
201
203
|
|
|
202
|
-
固定名 plan を `done/` へ移動する場合は、UTC
|
|
204
|
+
固定名 plan を `done/` へ移動する場合は、UTC タイムスタンプと4バイトの乱数を付けます。同じ名前が既にある場合は、既存ファイルを上書きせず末尾に連番を加えます。
|
|
203
205
|
|
|
204
206
|
```text
|
|
205
|
-
exec/plans/done/<slug>-<UTC>-<rand
|
|
207
|
+
exec/plans/done/<slug>-<UTC>-<rand>[-<sequence>]-plan.md
|
|
206
208
|
```
|
|
207
209
|
|
|
208
210
|
不要な plan は `done/` へ移動せず削除してもかまいません。plan は catalog と schedule から再生成でき、result が記録として残るためです。
|
|
@@ -67,13 +67,17 @@ Your nickname [owner]: owner
|
|
|
67
67
|
Your display name [Project Owner]: 店主
|
|
68
68
|
Orchestrator providers (...) [codex]: claude <- 使う AI ツールを 1 つ選ぶ
|
|
69
69
|
Delegate work to agents (exec)? [y/N]: <- Enter(実戦は後で設定する)
|
|
70
|
-
Create a Dev Container? [y/N]:
|
|
70
|
+
Create a Dev Container? [y/N]: y <- y(Dev Container を作る。使わない場合は Enter)
|
|
71
|
+
Add the recommended Dev Container settings? [Y/n]: <- Enter(推奨 preset を入れる)
|
|
72
|
+
Create Git hooks with lefthook? [y/N]: <- Enter(この体験では作らない)
|
|
71
73
|
```
|
|
72
74
|
|
|
73
75
|
入力が不正な場合は理由が表示され、同じ質問だけがもう一度表示されます。たとえば provider に
|
|
74
76
|
`claud` と入力すると、利用可能な provider の一覧に続いて provider の質問だけが再表示されます。
|
|
75
77
|
それまでに答えた project や名簿の内容を入力し直す必要はありません。
|
|
76
78
|
|
|
79
|
+
Dev Container を作る質問に `y`、推奨 preset に Enter(既定の「はい」)と答えると、tmux・Emacs・Vim・推奨の VS Code 拡張と設定・`.vscode/extensions.json` が入った環境が生成されます。作成したコンテナは、VS Code の「コンテナーで再度開く」または `devcontainer up` で開けます(詳しい説明は [[specdojo:remote-host-development-guide]] を参照)。Dev Container を使わずに手元の環境で進めたい場合は、Dev Container の質問に Enter または `n`(いいえ)と答えて先へ進めます。この 10 分の体験は記帳だけで進められるため、コンテナを開かずにそのままホスト環境で続けて構いません。
|
|
80
|
+
|
|
77
81
|
登録簿は `docs/ja/projects/prj-0001/controls/project-register/` に作られます。オーケストレーターで進める場合は、終了時に表示される `npm run orch:<provider>` で起動します。成果物カタログは対話では作られません。成果物の構成が定まったら、[[#41-成果物カタログを作成する|成果物カタログを作成する]] に従って `catalog_path` を設定し、`catalog scaffold` で追加してください。
|
|
78
82
|
|
|
79
83
|
### 1.2. 迷っていることを起票する(question)
|
|
@@ -224,7 +228,7 @@ npx specdojo init
|
|
|
224
228
|
```
|
|
225
229
|
|
|
226
230
|
`specdojo init` は、project ID と名前、人の nickname と表示名、利用する agent provider、
|
|
227
|
-
exec・Dev Container
|
|
231
|
+
exec・Dev Container・Git hook の要否を順に質問し、Dev Container を選んだ場合だけ推奨 preset を入れるか(既定は「はい」)を続けて質問します。Git hook は既定では作りません。成果物カタログは対話では質問せず、`--catalog <size>` を
|
|
228
232
|
明示した場合にだけ初期化時に作成します。選択に応じて設定、登録簿、人と
|
|
229
233
|
agent の名簿、provider の scaffold、`package.json` の `orch:<provider>`、exec の起動設定を
|
|
230
234
|
作成します。exec の親検証は、対応する npm script が `package.json` にあるものだけを設定し、
|
|
@@ -233,7 +237,7 @@ agent の名簿、provider の scaffold、`package.json` の `orch:<provider>`
|
|
|
233
237
|
それまでの回答は保持します。非対話環境や `--yes` では再質問せず、不正な指定をエラーとして終了します。
|
|
234
238
|
|
|
235
239
|
CI や標準入力が端末でない環境では質問しません。次のようにオプションだけで同じ初期設定を
|
|
236
|
-
|
|
240
|
+
行えます。`--devcontainer` を指定した場合は既定で推奨 preset(tmux・Emacs・Vim・推奨の VS Code 拡張と設定)が入ります(preset を使わない場合は `--devcontainer-preset none` を指定します)。省略値は画面に表示されます。
|
|
237
241
|
|
|
238
242
|
```bash
|
|
239
243
|
npx specdojo init --yes \
|
|
@@ -244,6 +248,7 @@ npx specdojo init --yes \
|
|
|
244
248
|
--provider claude,codex \
|
|
245
249
|
--exec \
|
|
246
250
|
--devcontainer \
|
|
251
|
+
--lefthook \
|
|
247
252
|
--dry-run
|
|
248
253
|
```
|
|
249
254
|
|
|
@@ -345,6 +350,26 @@ npx specdojo config scaffold --provider <name>
|
|
|
345
350
|
`<name>` には `antigravity`、`claude`、`codex`、`copilot`、`opencode` を指定します。従来の
|
|
346
351
|
`specdojo exec scaffold --provider <name>` も互換入口として利用できます。
|
|
347
352
|
|
|
353
|
+
commit 前に文書と SpecDojo の入力を検査する場合は、生成予定と `package.json` への追加内容を
|
|
354
|
+
dry-run で確認してから lefthook を配置します。
|
|
355
|
+
|
|
356
|
+
```bash
|
|
357
|
+
npx specdojo config scaffold --lefthook --dry-run
|
|
358
|
+
npx specdojo config scaffold --lefthook
|
|
359
|
+
npm install
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
生成した hook は、変更した Markdown と YAML だけを Prettier で整形し、変更した Markdown だけを
|
|
363
|
+
markdownlint で検査します。対象 project の `project_register_path` 配下を変更した場合は
|
|
364
|
+
`register build`、`catalog_path` 配下を変更した場合は `catalog validate` も実行します。
|
|
365
|
+
`catalog_path` がない構成には catalog の検査を生成せず、時間のかかるテストも pre-commit には
|
|
366
|
+
含めません。SpecDojo の文書が通る `.markdownlint.jsonc` と、provider の agent 定義を検査から外す
|
|
367
|
+
`.markdownlintignore` も生成します。既存の markdownlint 設定と ignore は `--force` を付けても保持します。
|
|
368
|
+
`lefthook.yml` と `tools/` の既存ファイルは `--force` なしでは上書きしません。
|
|
369
|
+
必要な npm script と devDependencies は書き込み前に表示し、同名の既存項目は `--force` を付けても
|
|
370
|
+
保持します。linked worktree または `node_modules` がない環境では installer が安全に skip するため、
|
|
371
|
+
primary worktree で `npm install` または `node tools/install-lefthook.mjs` を実行してください。
|
|
372
|
+
|
|
348
373
|
Antigravity CLI を無人実行する場合は、先に dry-run でユーザー設定へ追加する permission rule を確認し、明示的に適用します。このグローバル設定は利用者のすべてのリポジトリに効きます。通常の scaffold はユーザーディレクトリへ触れません。
|
|
349
374
|
|
|
350
375
|
```bash
|
|
@@ -355,11 +380,11 @@ npx specdojo config scaffold --provider antigravity --global
|
|
|
355
380
|
Dev Container は任意です。分離された環境が必要な場合だけ、既存の `.devcontainer/` がないことと生成内容を dry-run で確認してから作成します。
|
|
356
381
|
|
|
357
382
|
```bash
|
|
358
|
-
npx specdojo devcontainer scaffold --provider <name> --dry-run
|
|
359
|
-
npx specdojo devcontainer scaffold --provider <name>
|
|
383
|
+
npx specdojo devcontainer scaffold --provider <name> --preset recommended --dry-run
|
|
384
|
+
npx specdojo devcontainer scaffold --provider <name> --preset recommended
|
|
360
385
|
```
|
|
361
386
|
|
|
362
|
-
Dev Container の `<name>` には `antigravity`、`claude`、`codex`、`opencode`
|
|
387
|
+
Dev Container の `<name>` には `antigravity`、`claude`、`codex`、`opencode` を指定します。`--preset recommended` を指定すると、tmux・Emacs・Vim・推奨の VS Code 拡張と設定がまとめて設定されます。既存の `.devcontainer/` は通常実行では上書きされません。生成設定は provider の設定ディレクトリを名前付きボリュームに保存し、ホストの認証情報・秘密鍵・`.env` はマウントしません。preset を使わない場合、Ollama 接続、cron、tmux は必要な場合だけ `--ollama`、`--cron`、`--tmux` で個別に足せます。詳しい説明は [[specdojo:remote-host-development-guide]] を参照してください。
|
|
363
388
|
|
|
364
389
|
設定したプロジェクトを確認します。
|
|
365
390
|
|
|
@@ -83,6 +83,16 @@ specdojo register add --project <project-id> --type todo \
|
|
|
83
83
|
--title "在庫初期データの登録" --topic inventory-seed
|
|
84
84
|
```
|
|
85
85
|
|
|
86
|
+
別の project の作業ツリーから起票する場合は、対象 project と `--commit` を明示します。
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
specdojo register add --project prj-0002 --type todo \
|
|
90
|
+
--title "共通 API の変更を追跡する" --topic shared-api-change \
|
|
91
|
+
--from prj-0001:PJR-AB12 --commit
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
この経路は対象 project の `integration_branch`(省略時は `project/<project-id>/develop`)を開いている worktree を使い、無ければ一時 worktree を作ります。対象 project の名簿で `--by` を検証し、`register lifecycle` 枠の内側で起票、派生ビュー再生成、1 件の commit を行います。対象登録簿に未 commit 変更がある場合、または統合ブランチが存在しない場合は書き込みません。`--commit` のない別 project への起票と、別 project の項目に対する状態遷移は行えません。状態遷移は対象 project の作業ツリーで実行してください。
|
|
95
|
+
|
|
86
96
|
タイトルが日本語の場合は、内容を表す英語の `--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 を作る・直す手順」を参照してください)。
|
|
87
97
|
|
|
88
98
|
`--priority` は次の目安で付けます(省略時は `medium`)。
|
|
@@ -147,6 +157,27 @@ type は派生ビューの生成と `exec run --register` の挙動(`agent実
|
|
|
147
157
|
}
|
|
148
158
|
```
|
|
149
159
|
|
|
160
|
+
#### actor の指定
|
|
161
|
+
|
|
162
|
+
`register add`・`update`・`renumber` と状態遷移コマンドの `--by` は、次の名前だけを受け付けます。未知の名前を警告だけで記録する互換設定はありません。監査記録の追跡不能を残さないため、書き込み前にエラーで停止します。
|
|
163
|
+
|
|
164
|
+
- 人が操作・決定・承認した場合: project の `pm-members.yaml` にある本人の nickname
|
|
165
|
+
- agent が実行した場合: `.specdojo/agent-members.yaml` の nickname または alias。alias は実体の nickname に解決して event へ記録する
|
|
166
|
+
- SpecDojo の機械的な記帳: `SpecDojo`
|
|
167
|
+
- 対話型オーケストレーター自身の操作: `specdojo-orchestrator`
|
|
168
|
+
- 夜間 runner の操作: `night-orchestrator`
|
|
169
|
+
|
|
170
|
+
`PO`・`DEV` などの Role code は責任区分であり、actor ではありません。利用者の決定や承認をオーケストレーターが代行記帳するときも、`specdojo-orchestrator` ではなく、事前に確認した利用者本人の nickname を渡します。`--by` を省略した場合の `SpecDojo` は CLI/runner の既定値であり、人の決定や承認を表すためには使いません。
|
|
171
|
+
|
|
172
|
+
過去の event は監査記録として書き換えません。このリポジトリで既に使われた旧名を読むときは、次の対応を手掛かりにします。`manual` と Role code の `PO` は実体を一意に決められないため、event の reason と Git 履歴を併せて確認します。
|
|
173
|
+
|
|
174
|
+
| 過去の actor | 現在たどる名前 |
|
|
175
|
+
| -------------------------------------- | -------------------------- |
|
|
176
|
+
| `orchestrator` / `claude-orchestrator` | `specdojo-orchestrator` |
|
|
177
|
+
| `codex-expert-executor` | `sol-executor` |
|
|
178
|
+
| `naoji3x` | `indie` |
|
|
179
|
+
| `manual` / `PO` | 一意に対応しない(要調査) |
|
|
180
|
+
|
|
150
181
|
- 状態遷移は `open` から終端まで順に辿る必要はありません。人が対応した項目や、対話型 orchestrator がその場で処理した項目は、`start` を経ずに `close` / `reject` して構いません。着手を記録していない時点の遷移を後から補うと、実際には起きていない事実がイベントログに残ります。詳しい基準は [プロジェクト登録簿 作成ルール](../rulebooks/pjr-rulebook.md) の `中間状態を経ない終端` を参照します。
|
|
151
182
|
- 直接終端させる場合は、誰がどの経路で対応したかを `register close --by <actor> --reason "<経路と根拠>"` で残します。exec 経由でないため plan / result / evidence が生成されず、実施内容と検証結果は個票の対応結果が唯一の記録になります。
|
|
152
183
|
- agent へ実行させる項目は `exec run --register` を使います。この経路では runner が `start` と `wait` / `review` を記録し、plan / result / evidence も残ります。着手の記録が要る項目は、この経路を選びます。
|
|
@@ -174,6 +205,8 @@ specdojo register close \
|
|
|
174
205
|
|
|
175
206
|
`--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 は行いません。
|
|
176
207
|
|
|
208
|
+
別 project への起票では、対象登録簿全体が clean であることを追加で確認します。元の作業ツリーのブランチと HEAD は変更しません。
|
|
209
|
+
|
|
177
210
|
### 2.2. 個票の作成
|
|
178
211
|
|
|
179
212
|
すべての登録項目は、type 別のテンプレート(`pjr-todo-template.md` など `pjr-<type>-template.md`)から作る個票です。`register add` は個票の Frontmatter に構造化フィールドを書き込み、H1 と本文にタイトル・説明を置きます。
|
|
@@ -345,6 +378,8 @@ specdojo register history --project <project-id> --since 2026-08-01 --json
|
|
|
345
378
|
|
|
346
379
|
## 3. agent実行・定期実行との連携
|
|
347
380
|
|
|
381
|
+
### 3.1. 通常の agent 実行
|
|
382
|
+
|
|
348
383
|
登録項目は `exec run --register` で agent に実行させられます。
|
|
349
384
|
|
|
350
385
|
```bash
|
|
@@ -381,6 +416,25 @@ specdojo exec run --project <project-id> --register PJR-0012 PJR-0013 --worktree
|
|
|
381
416
|
|
|
382
417
|
実行フローの詳細は [exec運用ガイド](exec-operation-guide.md) を参照します。
|
|
383
418
|
|
|
419
|
+
### 3.2. 完了条件を承認して夜間 queue に入れる
|
|
420
|
+
|
|
421
|
+
人が個票の完了条件と変更範囲を確認した todo または issue だけ、次のコマンドで夜間実行を承認します。個票を手編集せず、event に承認者と理由を残します。
|
|
422
|
+
|
|
423
|
+
```bash
|
|
424
|
+
specdojo register update --project <project-id> --id PJR-0012 \
|
|
425
|
+
--autopilot approved --by <approver> --reason "完了条件と変更範囲を承認"
|
|
426
|
+
|
|
427
|
+
# 承認を取り消す
|
|
428
|
+
specdojo register update --project <project-id> --id PJR-0012 \
|
|
429
|
+
--autopilot - --by <approver> --reason "夜間 queue から除外"
|
|
430
|
+
```
|
|
431
|
+
|
|
432
|
+
`autopilot: approved` は「現在の個票に書かれた完了条件」の承認です。夜間 orchestrator は印のある `open` の todo・issue だけを ID 順に選びます。decision、印のない項目、`waiting` の項目は実行しません。完了条件を変更した場合は一度承認を取り消し、変更後の条件を再確認して承認します。
|
|
433
|
+
|
|
434
|
+
夜間実行は `specdojo orchestrator night` が担います。worktree 隔離、post-review、自動 close / `waiting` への復帰を必須とし、件数、並列数、連続失敗停止、rate limit 時の fallback をオプションで制限します。承認範囲外の操作が必要になった失敗は、元項目を `derived_from` に持つ issue として起票します。結果は `execution/reports/night-orchestrator/` の朝報告 1 文書へ集約します。
|
|
435
|
+
|
|
436
|
+
定期起動は Job `job-night-approved-register` と routine `rtn-night-approved-register` を使います。サンプル routine は保護された運用設定を勝手に有効化しないため `enabled: false` です。人が 2 時(Asia/Tokyo)、一晩 10 件、並列 2、連続失敗 2 件、fallback executor を確認してから有効化してください。
|
|
437
|
+
|
|
384
438
|
## 4. 例外対応と特殊な運用
|
|
385
439
|
|
|
386
440
|
ID 重複の復旧と PO 留保事項の承認運用など、通常運用から外れる場面を扱います。
|