specdojo 0.2.1 → 0.3.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.
- package/.github/agents/specdojo-orchestrator.md +165 -0
- package/CHANGELOG.md +280 -0
- package/README.md +92 -42
- package/dist/agent-response.js +20 -0
- package/dist/agent.js +4 -4
- package/dist/build-command.js +28 -8
- package/dist/dashboard.js +122 -1
- package/dist/devcontainer-command.js +43 -0
- package/dist/devcontainer-scaffold.js +165 -0
- package/dist/exec-agent-config.js +107 -9
- package/dist/exec-agent-git-state.js +18 -0
- package/dist/exec-agent-protected-config.js +46 -8
- package/dist/exec-evidence.js +254 -11
- package/dist/exec-handoff.js +336 -0
- package/dist/exec-parent-validation.js +317 -43
- package/dist/exec-pipeline-state.js +74 -9
- package/dist/exec-plans.js +115 -113
- package/dist/exec-protection-handoff.js +43 -2
- package/dist/exec-provider-scaffold.js +247 -15
- package/dist/exec-register-resume.js +65 -19
- package/dist/exec-register.js +9 -3
- package/dist/exec-repo-integration.js +811 -0
- package/dist/exec-repo-trace.js +182 -0
- package/dist/exec-reporter.js +613 -132
- package/dist/exec-results.js +81 -56
- package/dist/exec-run-lock.js +110 -107
- package/dist/exec-run.js +1585 -356
- package/dist/exec-shared.js +7 -0
- package/dist/exec-slot-lock.js +242 -0
- package/dist/exec-task-repos.js +415 -0
- package/dist/exec-trial.js +51 -25
- package/dist/exec-worktree-command.js +87 -43
- package/dist/exec-worktree-ops.js +502 -57
- package/dist/exec-worktree.js +114 -27
- package/dist/exec.js +13 -6
- package/dist/grade-result.js +128 -0
- package/dist/grade.js +809 -72
- package/dist/init-command.js +443 -0
- package/dist/job.js +160 -10
- package/dist/orchestrator.js +213 -0
- package/dist/register-event-merge.js +169 -0
- package/dist/register-item.js +7 -1
- package/dist/register.js +294 -86
- package/dist/review-grade.js +252 -0
- package/dist/review-plan.js +111 -1
- package/dist/review-types.js +40 -1
- package/dist/routine.js +72 -5
- package/dist/schedule-build.js +2 -2
- package/dist/schedule.js +17 -4
- package/dist/specdojo-config.js +465 -19
- package/dist/specdojo-gitignore.js +135 -0
- package/dist/specdojo.js +6 -0
- package/dist/viewpoint-document-kinds-check.js +128 -0
- package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +348 -90
- package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +51 -17
- package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +7 -5
- package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +29 -31
- package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +34 -55
- package/docs/ja/specdojo/exec-templates/xrp-job-template.md +54 -0
- package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +28 -37
- package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +29 -34
- package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +30 -30
- package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +29 -34
- package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +29 -34
- package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +29 -34
- package/docs/ja/specdojo/exec-templates/xrp-template.md +29 -28
- package/docs/ja/specdojo/exec-templates/xrr-template.md +11 -9
- package/docs/ja/specdojo/guides/docs-editing-guide.md +20 -0
- package/docs/ja/specdojo/guides/docs-structure-guide.md +103 -70
- package/docs/ja/specdojo/guides/exec-config-guide.md +91 -47
- package/docs/ja/specdojo/guides/exec-operation-guide.md +124 -27
- package/docs/ja/specdojo/guides/exec-worktree-guide.md +40 -11
- package/docs/ja/specdojo/guides/kata-guide.md +4 -4
- package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +25 -4
- package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +1 -1
- package/docs/ja/specdojo/guides/practice-system-composition-guide.md +13 -13
- package/docs/ja/specdojo/guides/quick-start-guide.md +260 -30
- package/docs/ja/specdojo/guides/register-operation-guide.md +31 -14
- package/docs/ja/specdojo/guides/release-v0-3-0-migration-guide.md +264 -0
- package/docs/ja/specdojo/guides/remote-host-development-guide.md +22 -1
- package/docs/ja/specdojo/guides/review-guide.md +195 -158
- package/docs/ja/specdojo/guides/routine-operation-guide.md +74 -9
- package/docs/ja/specdojo/guides/ryu-guide.md +32 -30
- package/docs/ja/specdojo/guides/schedule-design-guide.md +10 -10
- package/docs/ja/specdojo/guides/schedule-operation-guide.md +1 -1
- package/docs/ja/specdojo/guides/specdojo-overview-guide.md +58 -33
- package/docs/ja/specdojo/guides/use-case-guide.md +3 -3
- package/docs/ja/specdojo/guides/waza-guide.md +15 -2
- package/docs/ja/specdojo/index.md +2 -2
- package/docs/ja/specdojo/philosophy/specdojo-philosophy.md +5 -5
- package/docs/ja/specdojo/recipes/bps-recipe.md +213 -0
- package/docs/ja/specdojo/recipes/pm-members-recipe.md +52 -117
- package/docs/ja/specdojo/references/command-reference.md +335 -92
- package/docs/ja/specdojo/references/deliverables-reference.md +1 -1
- package/docs/ja/specdojo/references/directory-layout-reference.md +13 -9
- package/docs/ja/specdojo/references/specdojo-config-reference.md +107 -24
- package/docs/ja/specdojo/rulebooks/bps-rulebook.md +132 -220
- package/docs/ja/specdojo/rulebooks/br-rulebook.md +6 -44
- package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +2 -0
- package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +0 -87
- package/docs/ja/specdojo/rulebooks/gl-rulebook.md +61 -39
- package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +0 -87
- package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +1 -33
- package/docs/ja/specdojo/rulebooks/opd-rulebook.md +0 -137
- package/docs/ja/specdojo/rulebooks/opr-rulebook.md +0 -247
- package/docs/ja/specdojo/rulebooks/otp-rulebook.md +0 -83
- package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +4 -2
- package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +78 -150
- package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +5 -4
- package/docs/ja/specdojo/rulebooks/sch-rulebook.md +1 -1
- package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +0 -11
- package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +0 -61
- package/docs/ja/specdojo/rulebooks/tml-rulebook.md +2 -47
- package/docs/ja/specdojo/samples/bps-sample.md +74 -21
- package/docs/ja/specdojo/samples/gl-sample.yaml +17 -1
- package/docs/ja/specdojo/samples/ifx-index-sample.yaml +28 -0
- package/docs/ja/specdojo/samples/pm-members-sample.yaml +2 -67
- package/docs/ja/specdojo/samples/pm-organization-sample.md +8 -7
- package/docs/ja/specdojo/samples/pm-raci-sample.md +1 -1
- package/docs/ja/specdojo/samples/tml-sample.yaml +40 -0
- package/docs/ja/specdojo/standards/document-metadata-standard.md +21 -16
- package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +14 -14
- package/docs/ja/specdojo/standards/job-definition-standard.md +37 -17
- package/docs/ja/specdojo/standards/people-and-organization-definition-standard.md +37 -32
- package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +1 -1
- package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +21 -11
- package/docs/ja/specdojo/templates/agent-members-template.yaml +25 -0
- package/docs/ja/specdojo/templates/bps-template.md +91 -0
- package/docs/ja/specdojo/templates/pm-members-template.yaml +2 -59
- package/docs/specdojo/schemas/v1/agent-members.schema.yaml +76 -0
- package/docs/specdojo/schemas/v1/exec-common.schema.yaml +4 -2
- package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +55 -2
- package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +93 -6
- package/docs/specdojo/schemas/v1/exec-reporter-output.schema.yaml +27 -78
- package/docs/specdojo/schemas/v1/gl.schema.yaml +87 -0
- package/docs/specdojo/schemas/v1/grade-result.schema.yaml +33 -0
- package/docs/specdojo/schemas/v1/job-run.schema.yaml +27 -0
- package/docs/specdojo/schemas/v1/job.schema.yaml +25 -0
- package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +49 -1
- package/docs/specdojo/schemas/v1/pm-members.schema.yaml +9 -169
- package/docs/specdojo/schemas/v1/pm-review-viewpoints.schema.yaml +100 -10
- package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +13 -0
- package/docs/specdojo/schemas/v1/routine-run.schema.yaml +3 -0
- package/docs/specdojo/schemas/v1/routine.schema.yaml +7 -0
- package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +110 -0
- package/package.json +15 -9
- package/templates/antigravity/README.md +27 -2
- package/templates/antigravity/{pm-members-snippet.yaml → agent-members-snippet.yaml} +8 -2
- package/templates/antigravity/exec-defaults-snippet.yaml +7 -6
- package/templates/antigravity/orchestrator.md +18 -7
- package/templates/antigravity/settings.global.json +55 -0
- package/templates/claude/agents/claude-executor.md +14 -0
- package/templates/claude/agents/claude-reporter.md +16 -0
- package/templates/claude/agents/specdojo-orchestrator.md +18 -7
- package/templates/claude/settings.edit.json +27 -1
- package/templates/codex/README.md +5 -4
- package/templates/codex/agents/specdojo-orchestrator.toml +18 -7
- package/templates/codex/orchestrator.md +18 -7
- package/templates/copilot/README.md +7 -5
- package/templates/copilot/{pm-members-snippet.yaml → agent-members-snippet.yaml} +4 -2
- package/templates/devcontainer/devcontainer.json +27 -0
- package/templates/devcontainer/emacs/init.el +88 -0
- package/templates/devcontainer/post-create.sh +62 -0
- package/templates/init-agent-members.yaml +200 -0
- package/templates/init-exec-defaults.yaml +72 -0
- package/templates/opencode/agents/specdojo-orchestrator.md +18 -7
- package/docs/ja/specdojo/exec-templates/xrp-viewpoint-detail-template.md +0 -7
- package/docs/ja/specdojo/exec-templates/xrr-viewpoint-detail-template.md +0 -7
|
@@ -19,6 +19,7 @@ SpecDojo で扱うドキュメントの編集に役立つ、Visual Studio Code
|
|
|
19
19
|
|
|
20
20
|
- 文書編集に役立つ VS Code 拡張と SpecDojo 拡張の導入方法・役割
|
|
21
21
|
- 見出し番号の付け方、Markdown プレビューの使い方、表の整形方法
|
|
22
|
+
- 文書サイトのビルド方法と、サイドバー・検索・package 同梱文書の扱い
|
|
22
23
|
|
|
23
24
|
**次に読む文書**
|
|
24
25
|
|
|
@@ -325,3 +326,22 @@ npx specdojo-docs-lint md-content \
|
|
|
325
326
|
--schema docs/ja/specdojo/schemas/v1/guide-content.schema.yaml \
|
|
326
327
|
--data "docs/ja/specdojo/guides/*-guide.md"
|
|
327
328
|
```
|
|
329
|
+
|
|
330
|
+
## 6. 文書サイトを確認する
|
|
331
|
+
|
|
332
|
+
VitePress の文書サイトが必要なリポジトリでは、任意パッケージ `@specdojo/docs-site` を導入します。CLI 本体の `specdojo` だけを使う場合、このパッケージは不要です。
|
|
333
|
+
|
|
334
|
+
```bash
|
|
335
|
+
npm install --save-dev @specdojo/docs-site
|
|
336
|
+
npx specdojo-docs-site build .
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
開発サーバは `npx specdojo-docs-site dev .` で起動します。`build` と `dev` は、利用リポジトリに存在しない package 同梱の kata・guide・reference を、gitignore 済みの `specdojo-kata-staging/` へ一時的に複製して `/ja/specdojo/` で配信します。eject 済みの文書は利用リポジトリ側を優先するため、サイト表示のために `kata install --all` を実行する必要はありません。
|
|
340
|
+
|
|
341
|
+
サイト上の情報量を抑えるため、ナビゲーションと検索には次の範囲を使います。
|
|
342
|
+
|
|
343
|
+
- `/ja/specdojo/` では SpecDojo 文書、`/ja/projects/<project-id>/` では対象 project の文書をサイドバーに表示します。
|
|
344
|
+
- plan / result / event などの実行記録はページとして公開しますが、サイドバーには列挙しません。project の dashboard から `exec-records.md` を経由して辿ります。
|
|
345
|
+
- ローカル検索は登録簿一覧 `pjr-index` を入口にし、個票、状態別などの派生ビュー、管理ログ、実行記録を検索インデックスから除外します。個票本文を探す場合は `pjr-index` から対象個票へ移動します。
|
|
346
|
+
|
|
347
|
+
ステージングの参照元、Mermaid SVG だけを生成するコマンドなど、package 固有の設定は `packages/docs-site/README.md` を参照してください。
|
|
@@ -19,7 +19,7 @@ SpecDojoで扱うドキュメントの全体構成について、以下のガイ
|
|
|
19
19
|
**この文書で分かること**
|
|
20
20
|
|
|
21
21
|
- SpecDojo Unit、文書分類、ドキュメントオーナー、命名方針、標準ディレクトリ構成の考え方
|
|
22
|
-
-
|
|
22
|
+
- 成果物と型(Kata、philosophy / standard / rulebook / recipe / sample / template)の関係
|
|
23
23
|
- 成果物カタログ(dct)・Schedule(sch)・実行管理(exec)の関係
|
|
24
24
|
|
|
25
25
|
**次に読む文書**
|
|
@@ -41,24 +41,24 @@ SpecDojoで扱うドキュメントの全体構成について、以下のガイ
|
|
|
41
41
|
| 確認したいこと | 読む章 |
|
|
42
42
|
| --------------------------------- | --------------------------------------------------------------------------------- |
|
|
43
43
|
| 文書の分類と責任の考え方 | `SpecDojoで扱うドキュメントの全体構成`〜`ドキュメントオーナー` |
|
|
44
|
-
| 成果物・DCT・Schedule・execの関係 |
|
|
44
|
+
| 成果物・DCT・Schedule・execの関係 | `成果物と型の関係`〜`成果物カタログ・Schedule・実行管理の関係` |
|
|
45
45
|
| ディレクトリの命名・構成方針 | `ディレクトリ・ファイルの命名ルール` 以降 |
|
|
46
|
-
| プロダクトと別リポジトリで運用 |
|
|
46
|
+
| プロダクトと別リポジトリで運用 | `別リポジトリ構成` |
|
|
47
47
|
| ファイル単位の完全な配置一覧 | [ディレクトリレイアウトリファレンス](../references/directory-layout-reference.md) |
|
|
48
48
|
|
|
49
49
|
## 1. SpecDojoで扱うドキュメントの全体構成
|
|
50
50
|
|
|
51
|
-
- SpecDojo は、1つの SpecDojo Unit で1つのプロダクト文脈を扱うことを基本とします。SpecDojo Unit
|
|
51
|
+
- SpecDojo は、1つの SpecDojo Unit で1つのプロダクト文脈を扱うことを基本とします。SpecDojo Unit とは、プロダクトドキュメント、プロジェクトドキュメント、型(Kata)をまとめて扱う論理的な管理境界です。
|
|
52
52
|
- 1つの SpecDojo Unit には、対象プロダクトを構築・改修するための複数のプロジェクトが存在します。プロジェクトごとにプロジェクトドキュメントを作成します。
|
|
53
|
-
-
|
|
53
|
+
- 既定の別リポジトリ構成では、プロダクトドキュメントをプロダクトリポジトリへ、プロジェクトドキュメントと型をプロジェクトリポジトリへ置きます。同一リポジトリ構成では、これらを1つのリポジトリの `docs/` ルートに置きます。
|
|
54
54
|
- 1つのリポジトリで複数プロダクトを扱う場合は、プロダクトごとに文書の管理境界を分け、それぞれを独立した SpecDojo Unit として扱います。
|
|
55
55
|
- 成果物IDは、原則として SpecDojo Unit 内で一意にします。複数の SpecDojo Unit を横断して扱う場合は、必要に応じて Unit ID と成果物IDの組み合わせで識別します。
|
|
56
56
|
|
|
57
57
|
### 1.1. 構成の選び方
|
|
58
58
|
|
|
59
|
-
利用プロジェクトでは、SpecDojo の成果物更新、登録簿の状態遷移、exec の実行記録をプロダクトの Git 履歴から分離する
|
|
59
|
+
利用プロジェクトでは、SpecDojo の成果物更新、登録簿の状態遷移、exec の実行記録をプロダクトの Git 履歴から分離する **別リポジトリ構成を既定**とします。成果物と実装が同じ変更で動き、履歴も一体として扱う必要がある場合に限り、同一リポジトリ構成を選びます。CLI はどちらの構成も許容し、この選択を強制しません。
|
|
60
60
|
|
|
61
|
-
|
|
61
|
+
別リポジトリ構成の配置と現行実装の制約は `別リポジトリ構成` を参照してください。
|
|
62
62
|
|
|
63
63
|
## 2. ドキュメントの分類
|
|
64
64
|
|
|
@@ -200,9 +200,9 @@ flowchart TB
|
|
|
200
200
|
- 図中のアーキテクチャ設計は、個別仕様に先立つ全体構造の設計を表します。
|
|
201
201
|
- 「業務要件を含む」とは、業務仕様の冒頭に業務要件相当(対象範囲・成功条件・制約等)を含めることを指します。
|
|
202
202
|
|
|
203
|
-
## 5.
|
|
203
|
+
## 5. 成果物と型の関係
|
|
204
204
|
|
|
205
|
-
|
|
205
|
+
成果物と、その作成を支援する型(Kata、philosophy / standard / rulebook / recipe / template / sample / guide / reference)の関係、各種別の役割、成果物への紐付け方(解決の仕組み)は [型の構成ガイド](practice-system-composition-guide.md) を正本とします。`approach` に応じた rulebook / recipe / sample / template の参照方針は [実践の進め方ガイド](ryu-guide.md) を参照してください。
|
|
206
206
|
|
|
207
207
|
## 6. 成果物カタログ・Schedule・実行管理の関係
|
|
208
208
|
|
|
@@ -342,64 +342,74 @@ product/
|
|
|
342
342
|
|
|
343
343
|
ファイル単位の完全なツリーは [ディレクトリレイアウトリファレンス](../references/directory-layout-reference.md) の `プロダクトドキュメントの構成` を参照してください。
|
|
344
344
|
|
|
345
|
-
## 10.
|
|
345
|
+
## 10. 別リポジトリ構成
|
|
346
346
|
|
|
347
|
-
|
|
347
|
+
別リポジトリ構成は、SpecDojo Unit の運用記録をプロダクトと同じリポジトリに置かず、プロジェクトリポジトリで管理する既定構成です。プロジェクトリポジトリとは、登録簿・計画・実行記録などのプロジェクトドキュメントと型を置くリポジトリです。1つのプロジェクトリポジトリに、複数のプロジェクトを格納できます。この構成により、SpecDojo のプロジェクト成果物、登録簿の状態遷移、exec の実行記録をプロダクトの Git 履歴から分離します。
|
|
348
348
|
|
|
349
349
|
### 10.1. 採用条件
|
|
350
350
|
|
|
351
|
-
| 利用形態 | 判断
|
|
352
|
-
| ----------------------------------------------------------------------- |
|
|
353
|
-
| 一般の利用プロジェクト |
|
|
354
|
-
| プロジェクト文書と SpecDojo の運用記録だけを扱う | `app1-specdojo/` 内で catalog、Schedule、exec、grade を完結できる
|
|
355
|
-
| プロダクト文書または実装を1つの登録簿項目で変更する |
|
|
356
|
-
| SpecDojo 自身の開発のように、成果物と実装が常に同じ変更・履歴として動く |
|
|
351
|
+
| 利用形態 | 判断 |
|
|
352
|
+
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------- |
|
|
353
|
+
| 一般の利用プロジェクト | 別リポジトリ構成を既定とする |
|
|
354
|
+
| プロジェクト文書と SpecDojo の運用記録だけを扱う | `app1-specdojo/` 内で catalog、Schedule、exec、grade を完結できる |
|
|
355
|
+
| プロダクト文書または実装を1つの登録簿項目で変更する | project に `repos` を宣言し、`exec run --worktree` で全リポジトリを統合する |
|
|
356
|
+
| SpecDojo 自身の開発のように、成果物と実装が常に同じ変更・履歴として動く | 例外として同一リポジトリ構成を選べる |
|
|
357
357
|
|
|
358
|
-
|
|
358
|
+
プロダクトリポジトリ(`app1/` など)を変更する項目は、`.specdojo/specdojo.config.json` の project に `repos` を宣言してから実行します。宣言の書き方は [[specdojo:specdojo-config-reference|specdojo.config.json リファレンス]] の「`repos`のキー」を参照してください。宣言できるプロダクトリポジトリの数に上限はなく、1つの項目でプロジェクトリポジトリと複数のプロダクトリポジトリを変更できます。宣言済みのリポジトリは exec のタスク対象にでき、`specdojo orchestrator launch` で起動したオーケストレーターも参照・変更できます。宣言していないリポジトリは exec とオーケストレーターの管理外であり、`app1-specdojo/` の agent から直接更新しません。
|
|
359
359
|
|
|
360
360
|
### 10.2. ディレクトリレイアウト
|
|
361
361
|
|
|
362
|
-
3つのルートを互いに独立したディレクトリとして配置します。`app1/` と `app1-specdojo/` はそれぞれ別の Git リポジトリです。`app1-worktrees/` は両リポジトリの外に置く worktree 用の領域です。
|
|
362
|
+
プロダクトごとの親ディレクトリ(例: `app1-workspace/`)の下に、3つのルートを互いに独立したディレクトリとして配置します。`app1/` と `app1-specdojo/` はそれぞれ別の Git リポジトリです。`app1-specdojo-worktrees/` は両リポジトリの外に置く worktree 用の領域です。
|
|
363
363
|
|
|
364
364
|
```text
|
|
365
|
-
workspace/
|
|
365
|
+
app1-workspace/
|
|
366
366
|
├── app1/ # プロダクトのリポジトリ
|
|
367
367
|
│ ├── src/
|
|
368
368
|
│ └── docs/ja/product/ # 実装と同期して更新するプロダクト文書
|
|
369
|
-
├── app1-specdojo/ #
|
|
369
|
+
├── app1-specdojo/ # プロジェクトリポジトリ
|
|
370
370
|
│ ├── .specdojo/
|
|
371
371
|
│ ├── docs/ja/projects/
|
|
372
372
|
│ └── package.json # npm i -D specdojo で CLI を導入する
|
|
373
|
-
└── app1-worktrees/
|
|
373
|
+
└── app1-specdojo-worktrees/ # task 単位の worktree 置き場
|
|
374
374
|
```
|
|
375
375
|
|
|
376
|
-
`.specdojo/specdojo.config.json` の project パスは `app1-specdojo/`
|
|
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
378
|
### 10.3. プロダクト文書の配置
|
|
379
379
|
|
|
380
380
|
プロダクト文書は実装と同期して改訂するため、`app1/docs/ja/product/` に置きます。README、ソースコードから生成する API リファレンス、パッケージ利用者向けの手順など、コードと同じ revision で読む付属文書も `app1/` に置きます。
|
|
381
381
|
|
|
382
|
-
`app1-specdojo/` には `docs/ja/projects/` と `docs/ja/specdojo/` を置きます。前者はプロジェクト固有の目的、判断、計画、実行記録、後者は運用に使う philosophy / standard / rulebook / recipe / sample / template
|
|
382
|
+
`app1-specdojo/` には `docs/ja/projects/` と `docs/ja/specdojo/` を置きます。前者はプロジェクト固有の目的、判断、計画、実行記録、後者は運用に使う philosophy / standard / rulebook / recipe / sample / template などの型です。この境界により、プロダクトの内容と同じ revision が必要な文書は `app1/`、SpecDojo の記帳と再利用可能な型は `app1-specdojo/` の履歴に残ります。
|
|
383
383
|
|
|
384
|
-
プロダクト文書の catalog `base_path` を別リポジトリへ解決する機能と、[[prj-0001:pjr-xkks-grade-sidecar|PJR-XKKS grade result のサイドカー化]] で定める成果物へ書き込まない grade
|
|
384
|
+
プロダクト文書の catalog `base_path` を別リポジトリへ解決する機能と、[[prj-0001:pjr-xkks-grade-sidecar|PJR-XKKS grade result のサイドカー化]] で定める成果物へ書き込まない grade 運用は、プロダクト文書を成果物として管理する場合の前提です。exec はプロダクト文書をファイルとして変更・統合できますが、catalog・grade・doc index の対象にはしません。
|
|
385
385
|
|
|
386
386
|
### 10.4. 現行実装の境界
|
|
387
387
|
|
|
388
|
-
|
|
388
|
+
`repos` を宣言した project では、exec がプロジェクトリポジトリと宣言したプロダクトリポジトリを1つのタスクとして扱います。現行実装が扱う範囲と、扱わない範囲は次のとおりです。
|
|
389
389
|
|
|
390
|
-
| 論点 |
|
|
391
|
-
| ----------------- |
|
|
392
|
-
| 編集対象の解決 |
|
|
393
|
-
| worktree の隔離 |
|
|
394
|
-
|
|
|
395
|
-
|
|
|
390
|
+
| 論点 | 現行実装の扱い |
|
|
391
|
+
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
392
|
+
| 編集対象の解決 | `targets`・`paths` の `<repo>:<path>`(例: `app1:src/auth/token.ts`)をプロダクトリポジトリのパスとして解決する。接頭辞の無い値は従来どおり解決する |
|
|
393
|
+
| worktree の隔離 | タスクごとに全リポジトリの worktree を作り、agent はプロジェクト worktree を `cwd` としてプロダクト worktree へ書き込む |
|
|
394
|
+
| 依存の導入 | プロダクト worktree の作成時に、追跡されている `package-lock.json` ごとにプロジェクト側と同じ `npm ci` を実行する。lock が無い場合は導入せずログに残す。`setup.install: false` のリポジトリと、再利用する worktree では導入しない |
|
|
395
|
+
| 統合 | runner がリポジトリごとに commit し、宣言順のプロダクト、最後にプロジェクトの順で統合する |
|
|
396
|
+
| commit のスコープ | 変更ファイルと commit 対象をリポジトリごとに計算し、evidence にはプロダクト側を `<repo>:<path>` で記録する |
|
|
397
|
+
| 親検証の実行場所 | `pipeline.parent_validations` の `{ id, repo }` で検証ごとにリポジトリを割り当てる |
|
|
398
|
+
| 保護設定の検査 | 保護設定と Git 状態の検査を全リポジトリの worktree に適用する |
|
|
396
399
|
|
|
397
|
-
|
|
400
|
+
次の範囲は扱いません。
|
|
401
|
+
|
|
402
|
+
- プロダクト文書の doc id による参照。プロダクト側の `targets` はパスで指定します。
|
|
403
|
+
- `exec worktree commit` / `merge` によるプロダクト側の統合。分割コマンドはプロジェクト側だけを統合し、プロダクト worktree に変更が残るタスクは commit の前に停止します。プロダクト側を含めた統合は `exec run --worktree` で行います。
|
|
404
|
+
- exec が起動する opencode agent からプロダクト worktree への書き込み。opencode は agent 定義の `permission.external_directory` で作業ディレクトリ外を拒否するため、runner が起動引数で許可を加えられません。対話型オーケストレーターは `specdojo orchestrator launch` が起動時の inline config へ宣言済みルートだけを注入するため、この制約の対象外です。
|
|
405
|
+
- 宣言していないリポジトリの変更。`app1/` を agent のサンドボックス外から直接更新したり、手動の Git 操作で exec の管理外の worktree を作ったりしません。
|
|
406
|
+
|
|
407
|
+
`repos` を宣言しない project(同一リポジトリ構成を含む)の worktree の配置、commit、統合は従来と変わりません。
|
|
398
408
|
|
|
399
409
|
### 10.5. result によるトレーサビリティ
|
|
400
410
|
|
|
401
|
-
プロダクト実装の変更を伴う項目では、登録簿の item ID
|
|
402
|
-
app 側の commit message と SpecDojo 側の result
|
|
411
|
+
プロダクト実装の変更を伴う項目では、登録簿の item ID をプロジェクト ID で修飾した `<project-id>:<item-id>`(例: `prj-0001:PJR-XXXX`)を履歴改変に依存しないトレースキーとし、
|
|
412
|
+
app 側の commit message と SpecDojo 側の result 本文の両方に記録します。登録簿の ID はプロジェクトの中でしか一意でないため、修飾しないと複数プロジェクトの構成やプロダクトリポジトリの履歴から所属を特定できません。result frontmatter は
|
|
403
413
|
scaffold の構造を維持し、独自キーを追加しません。
|
|
404
414
|
|
|
405
415
|
app 側では、対象項目に対応する commit message の body 末尾に `Refs:` trailer を記載します。
|
|
@@ -409,33 +419,44 @@ feat(auth): トークン失効処理を追加する
|
|
|
409
419
|
|
|
410
420
|
認証済み端末を紛失した場合に、利用者がセッションを失効できるようにする。
|
|
411
421
|
|
|
412
|
-
Refs: PJR-XXXX
|
|
422
|
+
Refs: prj-0001:PJR-XXXX
|
|
413
423
|
```
|
|
414
424
|
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
425
|
+
`specdojo.config.json` の project に `repos` を宣言し、`exec run --register` で項目を統合する場合は、runner が次を自動で行います。
|
|
426
|
+
|
|
427
|
+
- プロダクト側の exec branch の commit と、統合先ブランチへの merge commit の両方に `Refs: <project-id>:<item-id>` を付けます。プロダクト側の merge commit には、遷移や agent 名などプロジェクト側の記帳を複製しません。
|
|
428
|
+
- プロジェクト側の merge commit の `Refs:` も同じ修飾形で付けます。
|
|
429
|
+
- 宣言順にプロダクトを統合した後、プロジェクトを統合する前に、リポジトリごとの統合先ブランチと commit snapshot を result 本文の末尾に「トレーサビリティ」の章として記録します。統合を再開した場合は同じ章を書き直します。
|
|
430
|
+
|
|
431
|
+
`repos` を宣言しない project では、プロダクト側の統合と trace 表の記録は行いません。プロジェクト側の merge commit の `Refs:` だけが修飾形になります。
|
|
432
|
+
|
|
433
|
+
SpecDojo 側の result には、同じトレースキーと app 側の参照を本文へ記録します。commit hash は特定時点の
|
|
434
|
+
スナップショットであり、主たる参照にはしません。Pull Request を使わない場合は `PR` を
|
|
435
|
+
`not applicable` とし、理由を添えます。runner がローカルで統合した行は `not applicable` になります。
|
|
418
436
|
|
|
419
437
|
```markdown
|
|
420
|
-
| trace key
|
|
421
|
-
|
|
|
422
|
-
| PJR-XXXX
|
|
438
|
+
| trace key | repository | integration branch | PR | commit snapshot | recorded at |
|
|
439
|
+
| ------------------- | ---------- | ------------------ | -------------- | ------------------------------------------ | ------------------------ |
|
|
440
|
+
| `prj-0001:PJR-XXXX` | `app1` | `main` | #123 | `0123456789abcdef0123456789abcdef01234567` | 2026-10-01T00:00:00.000Z |
|
|
441
|
+
| `prj-0001:PJR-XXXX` | `app2` | `release` | not applicable | not applicable (no changes) | 2026-10-01T00:00:00.000Z |
|
|
423
442
|
```
|
|
424
443
|
|
|
425
444
|
次の規則で運用します。
|
|
426
445
|
|
|
427
|
-
- `Refs:`
|
|
428
|
-
しません。
|
|
446
|
+
- `Refs:` の値は `<project-id>:<item-id>` とし、item ID は登録簿の ID と完全一致させます。表示名や一時的な branch 名をトレースキーに
|
|
447
|
+
しません。1 つの commit が複数の項目に関わる場合は、`Refs:` を項目ごとに 1 行ずつ書きます。
|
|
448
|
+
- プロダクトリポジトリから参照される project ID は、別々のプロジェクトリポジトリの間で重ならないよう、意味のある名前(例: `app1`)にします。
|
|
429
449
|
- app 側の対象 commit には `Refs:` trailer を付けます。複数 commit を1つへ squash する場合は、
|
|
430
450
|
最終 commit message に trailer を1行残します。app のソースや設定ファイルへ逆参照を埋め込みません。
|
|
431
451
|
- PR を使う場合は、番号だけでリポジトリを特定できないため、result へ repository 名と PR 番号または
|
|
432
452
|
URL を対で記録します。
|
|
433
453
|
- app commit snapshot は、意図する統合先ブランチが実装変更を含んだ直後の40文字の完全長 hash と
|
|
434
454
|
します。merge commit が作られた場合はその merge commit、fast-forward または squash merge の
|
|
435
|
-
|
|
455
|
+
場合は統合後の先端を記録します。統合する変更が無かったリポジトリは `not applicable (no changes)` とします。
|
|
436
456
|
- 記録と確認は app 側の統合成功後、SpecDojo 側の result と成果物を統合する前に行います。app 側への
|
|
437
457
|
統合が未完了なら PR や hash を推測で記録しません。
|
|
438
458
|
- 文書のみの項目で app 側の変更がない場合は、`app change: not applicable` とその理由を記録します。
|
|
459
|
+
- 過去の commit の `Refs: PJR-XXXX`(修飾なし)は書き換えません。検索するときは修飾形と修飾なしの両方を対象にします。
|
|
439
460
|
|
|
440
461
|
#### 10.5.1. rebase / squash merge 後の確認
|
|
441
462
|
|
|
@@ -443,26 +464,32 @@ rebase や squash により commit hash は変わるため、統合後の commit
|
|
|
443
464
|
いることを完了条件として確認します。
|
|
444
465
|
|
|
445
466
|
1. rebase 後は、書き換え後の各対象 commit の message を確認する。commit をまとめた場合は、残った
|
|
446
|
-
commit の body 末尾に `Refs: PJR-XXXX` があることを確認する。
|
|
447
|
-
2. squash merge では、最終 commit message を確定する画面またはコマンドで `Refs: PJR-XXXX` を
|
|
467
|
+
commit の body 末尾に `Refs: prj-0001:PJR-XXXX` があることを確認する。
|
|
468
|
+
2. squash merge では、最終 commit message を確定する画面またはコマンドで `Refs: prj-0001:PJR-XXXX` を
|
|
448
469
|
明示的に残す。プラットフォームによる commit message の自動連結には依存しない。
|
|
449
470
|
3. 統合後の app リポジトリで次を実行し、統合先ブランチから到達可能な commit が表示されることを
|
|
450
471
|
確認する。
|
|
451
472
|
|
|
452
473
|
```bash
|
|
453
|
-
git log <target-branch> --grep='^Refs: PJR-XXXX$' --format='%H %s'
|
|
474
|
+
git log <target-branch> --grep='^Refs: prj-0001:PJR-XXXX$' --format='%H %s'
|
|
454
475
|
```
|
|
455
476
|
|
|
456
477
|
1. 表示された最終 hash と PR 番号または URL を result へ記録する。対象 commit が表示されなければ、
|
|
457
478
|
SpecDojo 側を統合せず、app 側のトレースキーを是正する。
|
|
458
479
|
|
|
480
|
+
修飾形を導入する前の履歴も含めて検索する場合は、修飾なしの `Refs: PJR-XXXX` も対象にします。修飾なしの ID は別のプロジェクトの同じ ID にも一致し得るため、表示された commit がどのプロジェクトの項目かを result や期間で確かめます。
|
|
481
|
+
|
|
482
|
+
```bash
|
|
483
|
+
git log <target-branch> -E --grep='^Refs: (prj-0001:)?PJR-XXXX$' --format='%H %s'
|
|
484
|
+
```
|
|
485
|
+
|
|
459
486
|
この確認により、rebase や squash で hash が変わっても item ID から app の到達可能な履歴を検索
|
|
460
487
|
できます。PR は squash 後の commit とレビュー経緯を結ぶ補助参照、hash は確認時点を固定する補助値
|
|
461
488
|
です。
|
|
462
489
|
|
|
463
490
|
#### 10.5.2. 逆参照の範囲
|
|
464
491
|
|
|
465
|
-
|
|
492
|
+
別リポジトリ構成は SpecDojo の状態遷移や実行記録を app の履歴から分離しますが、app の変更理由を
|
|
466
493
|
登録簿へ結び直す最小限の逆参照として、commit message の `Refs:` trailer は必須とします。app の
|
|
467
494
|
ファイルへの ID 追記、SpecDojo の遷移 commit の複製、2つのリポジトリの原子的な統合は求めません。
|
|
468
495
|
履歴を汚さない範囲を commit message 1行に限定し、履歴改変後の追跡可能性を優先します。
|
|
@@ -482,38 +509,44 @@ Detached Unit は SpecDojo の状態遷移や実行記録を app の履歴から
|
|
|
482
509
|
|
|
483
510
|
移行のために共有済みの app 履歴を rebase、amend、force-push しません。
|
|
484
511
|
|
|
485
|
-
### 10.6.
|
|
512
|
+
### 10.6. 複数リポジトリの worktree と統合順序
|
|
486
513
|
|
|
487
|
-
|
|
514
|
+
`repos` を宣言した project では、同じ task ID の下にリポジトリごとの worktree を作ります。プロジェクトリポジトリの worktree は予約名 `project`、プロダクトリポジトリの worktree は宣言した `name` のディレクトリに置きます。
|
|
488
515
|
|
|
489
516
|
```text
|
|
490
|
-
app1-worktrees/
|
|
517
|
+
app1-specdojo-worktrees/
|
|
491
518
|
└── <task-id>/
|
|
492
|
-
├──
|
|
493
|
-
|
|
519
|
+
├── project/ # app1-specdojo の worktree(agent の cwd)
|
|
520
|
+
├── app1/ # app1 の worktree
|
|
521
|
+
└── app2/ # app2 の worktree(宣言した場合)
|
|
494
522
|
```
|
|
495
523
|
|
|
524
|
+
各 exec branch は、プロジェクト側が現在の統合先から、プロダクト側が `integration_branch`(省略時はそのリポジトリの現在のブランチ)の先端から作ります。agent はプロジェクト worktree を作業ディレクトリとし、プロダクト worktree の絶対パスを環境変数 `SPECDOJO_REPO_<NAME>` で受け取ります。provider ごとの書き込み許可は runner が起動引数へ付け足します。
|
|
525
|
+
|
|
496
526
|
統合は次の順序で行います。
|
|
497
527
|
|
|
498
|
-
1.
|
|
499
|
-
2.
|
|
500
|
-
|
|
501
|
-
|
|
528
|
+
1. 全リポジトリで commit 対象を commit し、merge できるかを事前に検査する。1つでも統合できないリポジトリがあれば、どのリポジトリも統合しない。
|
|
529
|
+
2. 宣言順にプロダクトの exec branch を統合先ブランチへ merge commit で統合する。プロダクト側の commit と merge commit には `Refs: <project-id>:<item-id>` を付ける(register 項目の場合)。
|
|
530
|
+
3. 統合後のプロダクトの trace key と commit snapshot を、プロジェクト側の result 本文へ記録する。
|
|
531
|
+
4. プロジェクトの exec branch を `app1-specdojo/` の統合先ブランチへ統合する。
|
|
532
|
+
5. 全リポジトリの統合後に、全リポジトリの worktree と exec branch をまとめて撤去する。
|
|
502
533
|
|
|
503
|
-
ソースを先に統合することで、プロダクトの統合を SpecDojo
|
|
534
|
+
ソースを先に統合することで、プロダクトの統合を SpecDojo 側の統合成否から切り離します。プロジェクト側の記帳(`review` への遷移と result)は、プロダクトがすべて統合された後にだけ統合先へ入ります。
|
|
504
535
|
|
|
505
|
-
|
|
506
|
-
| ----------------------- | --------------------------- | --------------------------------------------------------------------- |
|
|
507
|
-
| app 側の統合が失敗 | app / SpecDojo ともに未統合 | 項目を `waiting` とし、app 側の統合から再開する |
|
|
508
|
-
| SpecDojo 側の統合が失敗 | app のみ統合済み | 項目を `waiting` とし、app を再統合せず SpecDojo 側の統合だけ再開する |
|
|
536
|
+
### 10.7. 複数リポジトリの統合の失敗と再開
|
|
509
537
|
|
|
510
|
-
|
|
538
|
+
統合が途中で失敗した場合、失敗位置より前のリポジトリは統合済みのまま残り、失敗位置から後ろは統合しません。Git は複数リポジトリの原子的な更新を持たないため、runner は統合済みの範囲を巻き戻さず、リポジトリ別の状態を記録して失敗位置から再開します。
|
|
511
539
|
|
|
512
|
-
|
|
540
|
+
| 失敗箇所 | 統合状態 | 登録簿と再開の扱い |
|
|
541
|
+
| ------------------------ | -------------------------------------------- | --------------------------------------------------------------------------- |
|
|
542
|
+
| 事前検査 | 全リポジトリが未統合 | 項目を `waiting` とし、原因を解消してから統合段を再開する |
|
|
543
|
+
| n 番目のプロダクトの統合 | 1〜n-1 番目のプロダクトだけ統合済み | 項目を `waiting` とし、統合済みのプロダクトを飛ばして n 番目から再開する |
|
|
544
|
+
| プロジェクトの統合 | 全プロダクトが統合済み、プロジェクトは未統合 | 項目を `waiting` とし、プロダクトを再統合せずプロジェクトの統合だけ再開する |
|
|
513
545
|
|
|
514
|
-
|
|
546
|
+
- リポジトリ別の状態(`pending` / `merged` / `unchanged` / `failed`)は、run の `pipeline-state.json` の `stages.integrate.repos` に記録します。失敗の詳細は同じ run の `integrate.log` に残ります。
|
|
547
|
+
- `block_reason` には、失敗したリポジトリ、統合済みのリポジトリ、未統合のリポジトリを記録します。
|
|
548
|
+
- 失敗後も全リポジトリの worktree と exec branch を保持します。原因を解消した後、`exec run --register <item-id> --worktree --resume` で統合段から再開します。agent は再実行しません。
|
|
549
|
+
- 再開の前に、runner は未統合のリポジトリにだけ統合先の最新を取り込みます。`stages.integrate.repos` で統合済み(`merged` / `unchanged`)のプロダクトは取り込まず、exec branch に merge commit を作りません。
|
|
550
|
+
- 再開時は、統合先へ取り込み済みのプロダクトを merge し直さず、最初の統合で作った merge commit を result の trace 表へ記録します。
|
|
515
551
|
|
|
516
|
-
|
|
517
|
-
- **agent の作業ディレクトリ**: `<task-id>/` を agent の作業ディレクトリとして両 worktree を読み書き可能にし、`paths` と `targets` の解決基準を明示する。
|
|
518
|
-
- **失敗時の worktree 保持**: 失敗した段と統合済みのリポジトリを識別し、調査・再開に必要な worktree の保持と撤去条件を定める。
|
|
519
|
-
- **統合処理の複製**: commit 対象の算出、branch への統合、統合済み判定、pipeline state の記録を repo / worktree の2組に対応させ、app → SpecDojo の順序と再開位置を保存する。
|
|
552
|
+
一部のリポジトリだけが統合済みの状態は完了ではないため、`review` へ進めません。統合を打ち切る場合、統合済みのプロダクトの変更を残すか revert するかは、通常の統合後の判断として人が決めます。自動的に履歴を巻き戻しません。
|