specdojo 0.4.5 → 0.4.7
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 +4 -4
- package/CHANGELOG.md +41 -0
- package/dist/catalog/document-target.js +75 -0
- package/dist/commands/agent.js +2 -80
- package/dist/commands/init.js +33 -7
- package/dist/devcontainer/scaffold.js +5 -1
- package/dist/exec/agent-config.js +28 -16
- package/dist/exec/agent-plan.js +108 -0
- package/dist/exec/commands.js +3 -3
- package/dist/exec/evidence.js +35 -3
- package/dist/exec/grade-checkpoint.js +12 -0
- package/dist/exec/pipeline-state.js +1 -0
- package/dist/exec/plans-core.js +11 -67
- package/dist/exec/plans-generation.js +22 -5
- package/dist/exec/project.js +4 -1
- package/dist/exec/register-resume.js +8 -4
- package/dist/exec/register.js +66 -5
- package/dist/exec/reporter.js +8 -1
- package/dist/exec/results.js +1 -1
- package/dist/exec/run/agent-pipeline.js +7 -5
- package/dist/exec/run/agent.js +14 -1
- package/dist/exec/run/lifecycle-commands.js +2 -0
- package/dist/exec/run/register-resume.js +2 -0
- package/dist/exec/run/register-state.js +4 -1
- package/dist/exec/run/register-worktree.js +8 -1
- package/dist/exec/run/schedule-prepare.js +7 -1
- package/dist/exec/worktree-command.js +8 -1
- package/dist/exec/worktree-ops-lifecycle.js +4 -2
- package/dist/exec/worktree-ops-merge.js +40 -1
- package/dist/grade/apply.js +7 -5
- package/dist/grade/command-inspect.js +2 -1
- package/dist/grade/command-run.js +39 -0
- package/dist/grade/grade.js +3 -1
- package/dist/grade/markdown.js +4 -4
- package/dist/grade/pipeline-state.js +8 -6
- package/dist/grade/plan.js +8 -6
- package/dist/grade/run.js +307 -0
- package/dist/grade/target-discovery.js +1 -1
- package/dist/grade/targets.js +44 -22
- package/dist/kata/command.js +54 -9
- package/dist/register/approach.js +16 -0
- package/dist/register/core.js +2 -0
- package/dist/register/create-commands.js +57 -7
- package/dist/register/deliverable-target.js +215 -0
- package/dist/register/events.js +4 -0
- package/dist/register/external-project.js +18 -7
- package/dist/register/item.js +8 -0
- package/dist/register/views.js +3 -0
- package/dist/review/grade.js +19 -17
- package/dist/shared/agent-plan.js +1 -0
- package/dist/shared/git.js +3 -2
- package/dist/shared/lefthook-scaffold.js +5 -22
- package/dist/shared/markdownlint-scaffold.js +67 -0
- package/dist/shared/provider-scaffold.js +7 -5
- package/dist/shared/slidev-scaffold.js +102 -0
- package/dist/shared/specdojo-config.js +9 -3
- package/dist/specdojo.js +5 -1
- package/docs/ja/specdojo/exec-templates/xep-register-template.md +5 -4
- package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +2 -2
- package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +2 -2
- package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +2 -2
- package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +2 -2
- package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +2 -2
- package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +2 -2
- package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +2 -2
- package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +2 -2
- package/docs/ja/specdojo/exec-templates/xrp-template.md +2 -2
- package/docs/ja/specdojo/guides/exec-config-guide.md +81 -19
- package/docs/ja/specdojo/guides/exec-operation-guide.md +4 -0
- package/docs/ja/specdojo/guides/kata-guide.md +108 -1
- package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +6 -6
- package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +3 -1
- package/docs/ja/specdojo/guides/quick-start-guide.md +22 -2
- package/docs/ja/specdojo/guides/register-operation-guide.md +2 -0
- package/docs/ja/specdojo/guides/remote-host-development-guide.md +15 -1
- package/docs/ja/specdojo/guides/review-guide.md +2 -2
- package/docs/ja/specdojo/guides/ryu-guide.md +12 -0
- package/docs/ja/specdojo/references/command-reference.md +178 -62
- package/docs/ja/specdojo/references/specdojo-config-reference.md +31 -8
- package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +28 -22
- package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +17 -1
- package/docs/specdojo/schemas/v1/grade-pipeline-state.schema.yaml +1 -1
- package/docs/specdojo/schemas/v1/register-events.schema.yaml +2 -0
- package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +33 -1
- package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +16 -3
- package/package.json +5 -5
- package/templates/antigravity/orchestrator.md +4 -4
- package/templates/claude/README.md +2 -0
- package/templates/claude/agents/specdojo-orchestrator.md +4 -4
- package/templates/codex/README.md +38 -9
- package/templates/codex/agents/codex-executor.toml +1 -1
- package/templates/codex/agents/codex-expert-executor.toml +1 -1
- package/templates/codex/agents/codex-expert-review-executor.toml +1 -1
- package/templates/codex/agents/codex-review-executor.toml +1 -1
- package/templates/codex/agents/specdojo-orchestrator.toml +5 -5
- package/templates/codex/orchestrator.md +4 -4
- package/templates/devcontainer/devcontainer.json +1 -0
- package/templates/init-agent-members.yaml +131 -16
- package/templates/opencode/README.md +118 -14
- package/templates/opencode/agents/specdojo-orchestrator.md +5 -5
- package/templates/opencode/opencode.json +25 -0
|
@@ -90,6 +90,10 @@ register 実行は exec events を記録しないため、schedule の Ready・C
|
|
|
90
90
|
|
|
91
91
|
worktree の checkpoint 作成時に root の index に staged 変更がある場合、checkpoint 対象の plan、result、event、登録簿記帳と重なるパスだけを停止理由にします。重ならない staged 変更はパスを警告へ表示して保持したまま実行を続けます。checkpoint または register の runner commit が失敗した場合も、runner が対象にしたパスだけを unstage し、無関係な staged 変更は変更しません。
|
|
92
92
|
|
|
93
|
+
grade の結果・完了条件・未完了段のサイドカー(`execution_path/grade/results/`、`criteria/`、`pipeline/`)の未コミット変更も checkpoint に含めます。worktree は分岐前の評価結果を読み取り、更新したサイドカーを統合します。分岐後に root で同じサイドカーが更新された場合は、古い評価で上書きしないよう統合を止めます。両側の評価対象と内容を照合してから再開してください。
|
|
94
|
+
|
|
95
|
+
schedule の review 前の評価は、同じ package の `grade run` を起動します。最新の評価結果は再利用し、必要な評価では選択済み review agent の実体名と起動設定を引き継ぎます。開発用スクリプトの配置は不要です。失敗時は対象文書と理由を review plan に示し、review が評価結果の鮮度・利用可否を判断します。`viewpoints_path` がない project では同梱の `specdojo:pm-review-viewpoints` を参照し、固有の差分が必要なら設定したパスへ `exec scaffold --project <id>` で雛形を生成します。
|
|
96
|
+
|
|
93
97
|
register 実行の場所は `.specdojo/exec-defaults.yaml` の `run.register_execution`(`worktree` / `in-place`)で選びます。設定がない既存リポジトリは互換性のため in-place のままです。CLI の `--worktree` / `--in-place` は設定を上書きし、両方を同時に指定するとエラーになります。
|
|
94
98
|
|
|
95
99
|
通常は、失敗時の変更を隔離でき、`--resume` / `--force-restart` を使える worktree を選びます。worktree の準備時間が作業時間に見合わない、変更対象が小さく、失敗時に作業ツリーへ残る差分をその場で整理できる場合だけ `--in-place` を使います。in-place では `--resume` / `--force-restart` / `--join` と `--parallel` は使えません。`--register-commit` は in-place だけで意味を持ち、worktree は常に checkpoint と統合 commit を作ります。
|
|
@@ -89,7 +89,114 @@ template は、記述する部分を _TODO_ などのプレースホルダとし
|
|
|
89
89
|
|
|
90
90
|
型そのものの種別と型全体での位置づけは [型の構成ガイド](practice-system-composition-guide.md) を正本とします。
|
|
91
91
|
|
|
92
|
-
## 4.
|
|
92
|
+
## 4. Slidev の kata を検証する
|
|
93
|
+
|
|
94
|
+
スライドの sample・template を作る場合、SpecDojo を入れたリポジトリにも Slidev の実行環境を
|
|
95
|
+
用意すると、kata をビルドして確かめられます。新規導入は `specdojo init --slidev`、既存リポジトリへの
|
|
96
|
+
追加は次のコマンドを使います。`init` は Dev Container の `full` を選んだ場合だけ導入の既定が「はい」です。
|
|
97
|
+
オプションの詳細は [[specdojo:command-reference|コマンドリファレンス]] を参照してください。
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
specdojo config scaffold --slidev --dry-run
|
|
101
|
+
specdojo config scaffold --slidev
|
|
102
|
+
npm install
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
scaffold が加えるのは `@slidev/cli`・`prettier-plugin-slidev`・`prettier` の開発依存と、スライドだけを
|
|
106
|
+
整形する Prettier overrides、markdownlint の基本設定と Slidev 用の CLI2 overrides、CLI 用の除外です。
|
|
107
|
+
既存の依存の版は変えません。既存の設定・ignore は保持するため、表示された追加例を確認し、
|
|
108
|
+
足りない設定を手で統合してから整形・commit してください。
|
|
109
|
+
|
|
110
|
+
既定の対象は `docs/ja/specdojo/samples/**/*-slidev-sample.md` と
|
|
111
|
+
`docs/ja/specdojo/templates/**/*-slidev-template.md` です。たとえば利用者の `kata_authority` が
|
|
112
|
+
`edu-scratch` なら、sample は `docs/ja/specdojo/samples/edu-scratch/lesson-slidev-sample.md` に置きます。
|
|
113
|
+
別名の `lsd-sample.md` や旧配置の kata は、実際のパスを Prettier overrides の `files`、
|
|
114
|
+
`.markdownlint-cli2.yaml` の `overrides.filter`、`.markdownlintignore` の 3 か所に追加してください。
|
|
115
|
+
通常の Markdown として整形するとページ区切り直後の
|
|
116
|
+
設定が本文に変わる場合があるため、Slidev のファイルだけに `slidev` parser と
|
|
117
|
+
`prettier-plugin-slidev` を当てます。設定方法は [公式 plugin の説明](https://github.com/slidevjs/prettier-plugin) に従っています。
|
|
118
|
+
|
|
119
|
+
markdownlint の基本設定は `.markdownlintrc`(先頭が `{` の JSON)に置きます。commit hook と
|
|
120
|
+
`exec run` の result 検査は markdownlint-cli のままで、この基本設定と `.markdownlintignore` を読みます。
|
|
121
|
+
Slidev の kata は ignore で対象外にします。VS Code の markdownlint 拡張と CLI2 は
|
|
122
|
+
`.markdownlintignore` を読まないため、`.markdownlint-cli2.yaml` の `config.extends` から
|
|
123
|
+
`.markdownlintrc` を読み、Slidev 用の規則で検査します。スライドごとの見出しレベル・H1 とページ区切りに
|
|
124
|
+
隣接するブロックを許すため、基本設定に加えて `MD001`・`MD022`・`MD025`・`MD031`・`MD032` を外します。
|
|
125
|
+
|
|
126
|
+
CLI2 の overrides は最初の一致だけを使うため Slidev 用を先頭に置き、`filter` に対象 glob、
|
|
127
|
+
`combine: merge`、`config` に規則を指定します。Prettier は後の一致を優先するため Slidev 用を末尾に置きます。
|
|
128
|
+
通常の文書に対する規則は基本設定に残してください。
|
|
129
|
+
|
|
130
|
+
旧 scaffold の `.markdownlint.jsonc` などがある場合は、規則を JSON の `.markdownlintrc` に移し、
|
|
131
|
+
旧 `.markdownlint.*` を取り除き、CLI2 の `config.extends` を設定します。先頭にコメントを書くと
|
|
132
|
+
markdownlint-cli が JSON として読めません。親ディレクトリの `.markdownlint.*` も確認してください。
|
|
133
|
+
既存設定は `--force` でも自動移行しないため、表示された例を手で統合します。具体的な設定例と移行手順は
|
|
134
|
+
[[specdojo:command-reference|コマンドリファレンス]] の `config scaffold --lefthook` の説明を参照してください。
|
|
135
|
+
|
|
136
|
+
### 4.1. sample のビルドと表示
|
|
137
|
+
|
|
138
|
+
テーマの選定とインストールは利用者の作業です。scaffold は `slidev-theme-neversink` などのテーマを
|
|
139
|
+
選びません。sample の先頭の Slidev frontmatter の `theme` に合わせて開発依存を追加します。
|
|
140
|
+
たとえば `theme: default` を使う場合は次のようにします。
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
npm install --save-dev @slidev/theme-default
|
|
144
|
+
./node_modules/.bin/slidev build docs/ja/specdojo/samples/edu-scratch/lesson-slidev-sample.md --out "$PWD/tmp/slidev-dist"
|
|
145
|
+
./node_modules/.bin/slidev docs/ja/specdojo/samples/edu-scratch/lesson-slidev-sample.md
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
`build` の終了コードが 0 であることを確認し、表示されたローカル URL をブラウザで開いて、ページ区切り・
|
|
149
|
+
レイアウト・日本語・コンポーネントを確認します。CLI の引数は [Slidev 公式 CLI リファレンス](https://sli.dev/builtin/cli) を参照してください。
|
|
150
|
+
SSH / Dev Container 越しに開く場合は、開発サーバーのコマンドに `--remote` を加え、ポート 3030 を転送します。
|
|
151
|
+
`tmp/` は検証用の出力先なので、利用者の `.gitignore` に `/tmp/` を追加して管理対象から外してください。
|
|
152
|
+
|
|
153
|
+
### 4.2. 活動固有の部品と template
|
|
154
|
+
|
|
155
|
+
`ScratchBlocks.vue` などの活動固有のコンポーネント、`scratchblocks` などの追加依存、画像・
|
|
156
|
+
スタイル・setup は利用者がプロダクトリポジトリから用意します。部品に依存する場合は、sample を
|
|
157
|
+
`tmp/slidev-check/slides.md` にコピーし、同じ活動の `components/`・`public/` などをその横へ配置して、
|
|
158
|
+
相対参照を再現したうえで `./node_modules/.bin/slidev build tmp/slidev-check/slides.md --out "$PWD/tmp/slidev-dist"`
|
|
159
|
+
を実行します。template はプレースホルダを埋めた検証用コピーで同じ手順を使い、kata の原本を保持します。
|
|
160
|
+
|
|
161
|
+
PNG / PDF の書き出しに使う Playwright・Chromium、その OS ライブラリと日本語フォントは scaffold に
|
|
162
|
+
含みません。`slidev export` も行う場合は利用者が追加してください。ビルドとブラウザでの表示確認を先に行います。
|
|
163
|
+
|
|
164
|
+
## 5. kata の付属ファイル
|
|
165
|
+
|
|
166
|
+
`kata list` と `kata status` は、ID を読める形式(`.md`・`.mdx`・`.yaml`・`.yml`・`.json`)だけを
|
|
167
|
+
kata として表示します。この形式で ID の宣言がない場合は、従来どおりファイル名を ID とします。
|
|
168
|
+
CSS・画像など、それ以外の形式は独立した kata として表示しません。
|
|
169
|
+
|
|
170
|
+
付属ファイルは、kata と同じディレクトリに、最後の拡張子を除いた名前をそろえて置きます。
|
|
171
|
+
たとえば `lsd-sample.md` には `lsd-sample.css` を付けられます。複数の画像や部品は、同じ名前の
|
|
172
|
+
ディレクトリ `lsd-sample/` 以下にまとめられます。`generated/` 以下は対象外です。
|
|
173
|
+
ID を読める 5 形式のファイルは、同じ名前やディレクトリ内にあっても別の kata として扱い、
|
|
174
|
+
親 kata の付属ファイルには含めません。frontmatter に付属ファイルを宣言する必要はありません。
|
|
175
|
+
|
|
176
|
+
```text
|
|
177
|
+
samples/
|
|
178
|
+
lsd-sample.md
|
|
179
|
+
lsd-sample.css
|
|
180
|
+
lsd-sample/
|
|
181
|
+
images/
|
|
182
|
+
example.png
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
`specdojo kata eject --id <id>` は、同梱 kata とその付属ファイルを同じ相対パスへコピーします。
|
|
186
|
+
`--dry-run` では付属ファイルも 1 ファイルずつ表示し、書き込みません。既存ファイルはそれぞれ
|
|
187
|
+
`skip` となり、`--force` を付けた場合に上書きします。kata 本体が既存でも、未配置の付属ファイルは
|
|
188
|
+
コピーします。`kata install --all` も同じ規則で付属ファイルをコピーします。
|
|
189
|
+
|
|
190
|
+
コピー後に kata を別の場所で使う場合は、相対参照が保たれるよう付属ファイルも一緒に配置します。
|
|
191
|
+
Slidev の全ページに効かせる CSS は、検証用の `slides.md` の横へコピーするときに
|
|
192
|
+
`lsd-sample.css` を `style.css` にします。`kata eject` 自体は名前を変えません。
|
|
193
|
+
|
|
194
|
+
`kata status` は、eject 済みの kata 本体と付属ファイルをまとめて package と比較します。
|
|
195
|
+
付属ファイルだけの変更・追加・欠落も、親 kata の行を `modified` として表示します。
|
|
196
|
+
kata 本体が package にない場合は `package-missing`、package から参照中の場合は `-` です。
|
|
197
|
+
利用者の `kata_authority` に属する独自 kata の差分は、従来どおり `-` です。
|
|
198
|
+
|
|
199
|
+
## 6. 関連ドキュメント
|
|
93
200
|
|
|
94
201
|
- [実践の進め方ガイド](ryu-guide.md): `approach` の選び方・一覧、参照の共通原則、メンテナンス・review への適用
|
|
95
202
|
- [型の構成ガイド](practice-system-composition-guide.md): 実践の型を含む型(Kata)の種別と役割
|
|
@@ -48,10 +48,10 @@ CLI を直接操作する場合の代表フローは [遂行の技活用ガイ
|
|
|
48
48
|
| `orch:sonnet:work` | Claude Code / `sonnet` | `../worktrees/claude-work`(無ければ自動作成) |
|
|
49
49
|
| `orch:opus` | Claude Code / `opus` | なし |
|
|
50
50
|
| `orch:opus:work` | Claude Code / `opus` | `../worktrees/claude-work`(無ければ自動作成) |
|
|
51
|
-
| `orch:
|
|
52
|
-
| `orch:
|
|
53
|
-
| `orch:sol` | Codex / `gpt-
|
|
54
|
-
| `orch:sol:work` | Codex / `gpt-
|
|
51
|
+
| `orch:luna` | Codex / `gpt-6-luna` | なし |
|
|
52
|
+
| `orch:luna:work` | Codex / `gpt-6-luna` | `../worktrees/codex-work`(無ければ自動作成) |
|
|
53
|
+
| `orch:sol` | Codex / `gpt-6.1-sol` | なし |
|
|
54
|
+
| `orch:sol:work` | Codex / `gpt-6.1-sol` | `../worktrees/codex-work`(無ければ自動作成) |
|
|
55
55
|
| `orch:copilot` | GitHub Copilot | なし |
|
|
56
56
|
| `orch:copilot:work` | GitHub Copilot | `../worktrees/copilot-work`(無ければ自動作成) |
|
|
57
57
|
| `orch:qwen` | OpenCode / Qwen 3.8 | なし |
|
|
@@ -65,7 +65,7 @@ Antigravity CLI(`agy`)はファイル定義の agent を持たないため
|
|
|
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
|
|
68
|
+
`specdojo init` と `config scaffold` が利用者の `package.json` へ追加するスクリプトは、Claude Code が `orch:opus`・`orch:sonnet`、Codex が `orch:sol`(`gpt-6.1-sol`)・`orch:luna`(`gpt-6-luna`)、Antigravity が `orch:flash`、OpenCode が `orch:opencode` です。Codex と Antigravity のスクリプトは、名前に対応するモデルを起動コマンドで明示します。
|
|
69
69
|
|
|
70
70
|
0.4.0 以前に作った `orch:codex`・`orch:agy` は自動では削除・上書きされません。`config scaffold --provider codex` または `config scaffold --provider antigravity` を再実行して新しいスクリプトを追加し、新しい名前で起動できることを確認してから、旧スクリプトを `package.json` から削除してください。
|
|
71
71
|
|
|
@@ -82,7 +82,7 @@ npm run orch:opus
|
|
|
82
82
|
npm run orch:sonnet:work
|
|
83
83
|
```
|
|
84
84
|
|
|
85
|
-
frontier モデルは Claude Code が `opus`、Codex が `gpt-
|
|
85
|
+
frontier モデルは Claude Code が `opus`、Codex が `gpt-6.1-sol` に対応します。通常運用はそれぞれ既定の `sonnet` / `gpt-6-luna` を使います。
|
|
86
86
|
|
|
87
87
|
worktree 付きは、全 CLI で `tools/worktree/open-agent-worktree.sh` を通して固定名の worktree を使い、そこから `specdojo orchestrator launch` を起動します。無ければ起動時に作成します。ブランチは `worktree/<name>`、配置は `../worktrees/<name>` です。既存 worktree のブランチが一致しない場合は agent を起動しません。Claude Code の `--worktree` はブランチ名と配置を他の CLI に揃えられないため使用しません。
|
|
88
88
|
|
|
@@ -145,7 +145,9 @@ plan の構造と生成規則は schema・本ガイド・各テンプレート
|
|
|
145
145
|
|
|
146
146
|
`approach` が指定されていれば `xep-fully-guided-template.md`、`xep-recipe-guided-template.md`、`xep-freeform-template.md`、`xep-retrofit-template.md`、`xep-rulebook-maintenance-template.md` のような approach 別テンプレートを優先します。該当テンプレートが存在しない場合は標準テンプレートにフォールバックします。
|
|
147
147
|
|
|
148
|
-
|
|
148
|
+
register のカタログなしの成果物 plan は、個票の `target_path`・`target_rulebook` または既存文書の索引と frontmatter から対象を解決します。カタログの `done_criteria` がないことを明記し、個票の完了条件と rulebook を使います。`bootstrap` は未作成 kata の ID・パスと参照宣言の指示、`finalize`・`bootstrap-finalize` は既存成果物の確認チェック表と確定対象を plan に載せます。実 agent は `status: ready` への昇格を行いません。対象と起票の条件は [[specdojo:command-reference]] を参照してください。
|
|
149
|
+
|
|
150
|
+
`approach: retrofit` では、対象成果物の DCT エントリに宣言された `evidence_refs` を edit / review plan の「実装エビデンス」へ展開します。カタログ経由で `evidence_refs` がない場合は plan 生成をエラーにします。カタログなしでは実装の調査パスを個票に明記して調査入力とします。実装エビデンスは調査入力であり、frontmatter の `targets` には追加しません。実行者は実際に参照したパス、抽出した現在動作、成果物との一致・乖離、未確認範囲を result に記録します。
|
|
149
151
|
|
|
150
152
|
実践の型の扱いは [実践の進め方ガイド](ryu-guide.md) を参照します。
|
|
151
153
|
|
|
@@ -554,7 +554,7 @@ risk は必要なら `exec run --register` で軽減策を実行できます。n
|
|
|
554
554
|
|
|
555
555
|
### 3.6. 成果物を作る・直す
|
|
556
556
|
|
|
557
|
-
**こんなとき:**
|
|
557
|
+
**こんなとき:** 1 文書を、利用できる kata の整備状況に合う進め方で作成・更新したいとき。
|
|
558
558
|
|
|
559
559
|
| `approach` | 選ぶ状況 |
|
|
560
560
|
| --------------- | ---------------------------------------------------------------- |
|
|
@@ -578,7 +578,23 @@ npx specdojo exec run \
|
|
|
578
578
|
--worktree
|
|
579
579
|
```
|
|
580
580
|
|
|
581
|
-
`recipe-guided
|
|
581
|
+
`recipe-guided`・`freeform`・`retrofit` を使う場合は、上の `--approach fully-guided` を選んだ値へ置き換えます。`--target` は成果物の doc id を 1 件指定します。カタログにある対象は従来どおりカタログの `done_criteria` と個票の完了条件を使います。
|
|
582
|
+
|
|
583
|
+
カタログがない場合、既存文書は文書索引からパスと frontmatter の `specdojo.rulebook` を辿れます。これから作る文書は、次のようにリポジトリ相対のパスと rulebook ID を個票に保存します。
|
|
584
|
+
|
|
585
|
+
```bash
|
|
586
|
+
npx specdojo register add \
|
|
587
|
+
--project <project-id> --type todo \
|
|
588
|
+
--title "文書を実践の型に沿って作る" --topic create-document \
|
|
589
|
+
--approach fully-guided --target <deliverable-doc-id> \
|
|
590
|
+
--target-path docs/ja/product/example.md \
|
|
591
|
+
--target-rulebook <kata-authority>:example-rulebook
|
|
592
|
+
npx specdojo exec plan --project <project-id> --register <PJR-ID>
|
|
593
|
+
```
|
|
594
|
+
|
|
595
|
+
`--target-rulebook` の rulebook と、そこから参照する必要な kata は先に用意します。`fully-guided` は `not-needed` と宣言された型を除く一式、`recipe-guided` は recipe が必要です。不足する型は起票時に名前を示して停止します。個票の「完了条件」を具体化してから実行してください。カタログなしの完了基準は個票の完了条件と rulebook です。`retrofit` では調べる実装のパスも個票に明記します。
|
|
596
|
+
|
|
597
|
+
パスと rulebook は `register update --target-path <path> --target-rulebook <doc-id>` で更新でき、それぞれ `-` で削除できます。既存文書のパスや `specdojo.rulebook` と指定が食い違う場合は停止します。カタログ設定済みで対象が未登録の場合は、この 2 つを明示したときだけ同じ解決を使います。
|
|
582
598
|
|
|
583
599
|
### 3.7. 成果物とkataを一組で作る
|
|
584
600
|
|
|
@@ -600,6 +616,10 @@ npx specdojo exec run \
|
|
|
600
616
|
--worktree
|
|
601
617
|
```
|
|
602
618
|
|
|
619
|
+
カタログなしの `bootstrap` では、上の起票に `--target-path docs/ja/product/example.md --target-rulebook <kata-authority>:example-rulebook` を追加し、設定ファイルに `kata_authority` を指定します。新しい rulebook ID が必要で、既存 ID は受け付けません。plan は `docs/ja/specdojo/<kind>s/<kata-authority>/example-<kind>.md` に未作成の kata を示し、成果物の `specdojo.rulebook` と rulebook の kata 参照を記入するよう指示します。
|
|
620
|
+
|
|
621
|
+
`finalize`・`bootstrap-finalize` は既存文書だけを対象にできます。カタログなしでは個票の完了条件をチェック表にし、人が成果物を確定します。`bootstrap-finalize` は frontmatter から辿る kata 一式も確定対象です。`cross-deliverable-dedup` は成果物群を扱うためカタログが必要です。
|
|
622
|
+
|
|
603
623
|
`bootstrap` は初期整備用です。既に信頼できる kata が揃っている成果物の通常改訂には `fully-guided` を使います。
|
|
604
624
|
|
|
605
625
|
### 3.8. kataを直す
|
|
@@ -111,6 +111,8 @@ specdojo register add --project customer --type todo \
|
|
|
111
111
|
|
|
112
112
|
呼び出し元は相手の登録簿を直接編集せず、相手にインストールされた SpecDojo 0.4.2 以上へ処理を渡します。`--from customer:PJR-AB12` は相手の実 project ID に置き換えて検証・記録されます。相手のリポジトリや CLI がない場合、版が古い場合、`--commit` がない場合は起票前に停止します。相手への状態遷移は、相手のリポジトリへ移動して実行します。
|
|
113
113
|
|
|
114
|
+
SpecDojo 自身のリポジトリへ起票する場合も、同じように別名を宣言できます。相手で `npm install` と `npm run build` を実行しておきます。相手に `node_modules/.bin/specdojo` がなく、`package.json` の `name` が `specdojo` なら、呼び出し元と同じ Node.js で `node <相手>/dist/specdojo.js` を起動します。未ビルドの場合は `npm run build` を案内して停止し、版の条件(0.4.2 以上)も引き続き確認します。
|
|
115
|
+
|
|
114
116
|
タイトルが日本語の場合は、内容を表す英語の `--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 を作る・直す手順」を参照してください)。
|
|
115
117
|
|
|
116
118
|
`--priority` は次の目安で付けます(省略時は `medium`)。
|
|
@@ -89,7 +89,7 @@ scaffold は、常時稼働ホストへの接続と tmux セッションの維
|
|
|
89
89
|
|
|
90
90
|
`devcontainer.json` の `appPort` や `forwardPorts` で開発サーバなどの公開ポートを設定している場合は、接続用エイリアスに `LocalForward` の行が含まれます。開発サーバのポートを増やしたときは、`~/.ssh/config` の tmux 接続用エイリアスにも `LocalForward <ポート> 127.0.0.1:<ポート>` を追加してください。
|
|
91
91
|
|
|
92
|
-
生成される `devcontainer.json` は `remoteEnv` で `/home/node/.local/bin`(利用者が別の場合は `/home/<remoteUser>/.local/bin`)を `PATH` の先頭に追加するため、コンテナ作成後に開く端末や VS Code のターミナルでも `~/.local/bin` に入った Claude Code などの CLI
|
|
92
|
+
生成される `devcontainer.json` は `remoteEnv` で `/home/node/.local/bin`(利用者が別の場合は `/home/<remoteUser>/.local/bin`)を `PATH` の先頭に追加するため、コンテナ作成後に開く端末や VS Code のターミナルでも `~/.local/bin` に入った Claude Code などの CLI がそのまま利用できます。また、`shutdownAction: "none"` を設定しているため、VS Code などのクライアントを切断したりウィンドウを閉じたりしてもコンテナが停止せず、tmux セッションやバックグラウンド処理を維持できます。
|
|
93
93
|
|
|
94
94
|
### 2.2. 生成した Dev Container をホストで実地確認する
|
|
95
95
|
|
|
@@ -225,6 +225,20 @@ v0.4.0 などで生成した Dev Container 環境では、`devcontainer.json`
|
|
|
225
225
|
|
|
226
226
|
コンテナ内の利用者が `node` 以外の場合は、`/home/<remoteUser>/.local/bin` に合わせてください。
|
|
227
227
|
|
|
228
|
+
### 6.4. クライアント切断時にコンテナが停止する
|
|
229
|
+
|
|
230
|
+
以前のバージョンで生成した Dev Container 環境では、`devcontainer.json` に `shutdownAction` が指定されていないため、VS Code などのクライアントを切断した際にコンテナが自動的に停止し、コンテナ内で実行中の tmux セッションやバックグラウンド処理が中断することがあります。
|
|
231
|
+
|
|
232
|
+
既存の環境を修正するには、`.devcontainer/devcontainer.json` に `"shutdownAction": "none"` を追加してください。
|
|
233
|
+
|
|
234
|
+
```json
|
|
235
|
+
"workspaceFolder": "/workspaces/<親名>/<リポジトリ名>",
|
|
236
|
+
"shutdownAction": "none",
|
|
237
|
+
"init": true,
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
設定の反映には Dev Container の再起動(VS Code で「Rebuild Container」または `devcontainer up`)を行ってください。なお、切断後もコンテナが停止しない実際の動作確認は、Docker daemon が稼働しているホスト環境(または Dev Container CLI が動作する実環境)で行う必要があります。
|
|
241
|
+
|
|
228
242
|
## 7. 運用上のセキュリティ
|
|
229
243
|
|
|
230
244
|
この構成は、常時稼働ホストを外部から到達可能にします。次を守ります。
|
|
@@ -237,11 +237,11 @@ edit plan で観点別の自己レビューを行わないのは、各観点を
|
|
|
237
237
|
|
|
238
238
|
`specdojo exec run` は、`mode: review` のタスクの plan を生成する前に、runner 自身が評価対象へ grade を実行します。executor(review を行う agent)には grade を実行させません。評価の独立性を保つためです。
|
|
239
239
|
|
|
240
|
-
この自動 grade
|
|
240
|
+
この自動 grade は同じ npm package の `grade run` を使います。開発用スクリプトの配置は不要です。選択した review agent の実体名と起動設定を引き継ぎ、対象 1 件の plan 生成・評価・サイドカー反映を実行します。成果物の grade には project の `catalog_path` が必要です。単独の実行や部品ごとの手順は [[specdojo:command-reference|CLI コマンドリファレンス]] を参照してください。
|
|
241
241
|
|
|
242
242
|
- 評価対象は成果物です。`approach` が `rulebook-maintenance` / `recipe-maintenance` / `sample-maintenance` / `template-maintenance` の場合は、見直した実践の型そのものが評価対象になります(`--target kata`)。
|
|
243
243
|
- 評価対象の `content_hash` が既存の評価結果サイドカーの `content_hash` と一致する場合は、grade を再実行せず既存の評価結果を使います。どちらの場合も評価は 1 回です。
|
|
244
|
-
-
|
|
244
|
+
- grade は `grade run --path <対象文書>` で評価対象 1 件に絞って実行します。評価対象を解決できない場合と `--dry-run` の場合は実行しません。
|
|
245
245
|
- grade が失敗しても review は止めません。実行の結果と評価結果の鮮度を review plan に示し、review が verdict(`grade-stale` / `grade-unavailable` など)として記録します。
|
|
246
246
|
|
|
247
247
|
### 3.3. review plan の生成
|
|
@@ -205,6 +205,18 @@ flowchart LR
|
|
|
205
205
|
- 判断根拠の記録: 参照した文書・しなかった文書とその理由を成果物または result に残します(特に `recipe-guided` / `freeform`)。後から実践の型を整備する材料になります。
|
|
206
206
|
- 判定基準の優先: `done_criteria` と grade 結果が判定基準を示す場合はそれらを優先します。本原則は、判定基準だけでは読み取れない「どこまで参照に照らすか」を補います。
|
|
207
207
|
|
|
208
|
+
### 1.4. 成果物カタログなしで進める
|
|
209
|
+
|
|
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` です。既存文書と指定が矛盾した場合は停止します。
|
|
211
|
+
|
|
212
|
+
カタログの `done_criteria` はないため、個票の完了条件と rulebook を完了基準にします。`fully-guided` には `not-needed` を除く kata 一式、`recipe-guided` には recipe が必要で、不足すると起票時に停止します。`retrofit` では調べる実装のパスを個票に明記します。
|
|
213
|
+
|
|
214
|
+
`bootstrap` は kata の不足を許容し、パスと新規 rulebook ID、設定の `kata_authority` を必須とします。既存 rulebook は拒否します。rulebook ID の `-rulebook` より前の部分を共通の名前にして recipe・sample・template の ID を導出し、`docs/ja/specdojo/<kind>s/<kata_authority>/` の未作成候補を plan に載せます。作成した rulebook は成果物の `specdojo.rulebook` に記入します。
|
|
215
|
+
|
|
216
|
+
`finalize` と `bootstrap-finalize` の対象は既存文書だけです。個票の完了条件をチェック表にし、`finalize` は成果物、`bootstrap-finalize` は成果物と frontmatter から辿る kata 一式を人が確定します。
|
|
217
|
+
|
|
218
|
+
`cross-deliverable-dedup` はカタログの成果物群を対象にするため、引き続きカタログが必要です。カタログ設定済みの対象は従来の宣言を優先し、未登録の対象に限りパスと rulebook を両方明示した場合だけ上記の解決を使います。具体的な起票例は [[specdojo:quick-start-guide]]、オプションは [[specdojo:command-reference]] を参照してください。
|
|
219
|
+
|
|
208
220
|
## 2. 実践の型メンテナンスの進め方
|
|
209
221
|
|
|
210
222
|
`rulebook-maintenance` / `recipe-maintenance` / `sample-maintenance` / `template-maintenance` は、通常の成果物作業とは参照の向きが逆になる進め方です。作成・更新かレビューかを `mode`(`edit` / `review`)で表す点は他の `approach` と同じです。
|