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.
Files changed (101) hide show
  1. package/.github/agents/specdojo-orchestrator.md +4 -4
  2. package/CHANGELOG.md +41 -0
  3. package/dist/catalog/document-target.js +75 -0
  4. package/dist/commands/agent.js +2 -80
  5. package/dist/commands/init.js +33 -7
  6. package/dist/devcontainer/scaffold.js +5 -1
  7. package/dist/exec/agent-config.js +28 -16
  8. package/dist/exec/agent-plan.js +108 -0
  9. package/dist/exec/commands.js +3 -3
  10. package/dist/exec/evidence.js +35 -3
  11. package/dist/exec/grade-checkpoint.js +12 -0
  12. package/dist/exec/pipeline-state.js +1 -0
  13. package/dist/exec/plans-core.js +11 -67
  14. package/dist/exec/plans-generation.js +22 -5
  15. package/dist/exec/project.js +4 -1
  16. package/dist/exec/register-resume.js +8 -4
  17. package/dist/exec/register.js +66 -5
  18. package/dist/exec/reporter.js +8 -1
  19. package/dist/exec/results.js +1 -1
  20. package/dist/exec/run/agent-pipeline.js +7 -5
  21. package/dist/exec/run/agent.js +14 -1
  22. package/dist/exec/run/lifecycle-commands.js +2 -0
  23. package/dist/exec/run/register-resume.js +2 -0
  24. package/dist/exec/run/register-state.js +4 -1
  25. package/dist/exec/run/register-worktree.js +8 -1
  26. package/dist/exec/run/schedule-prepare.js +7 -1
  27. package/dist/exec/worktree-command.js +8 -1
  28. package/dist/exec/worktree-ops-lifecycle.js +4 -2
  29. package/dist/exec/worktree-ops-merge.js +40 -1
  30. package/dist/grade/apply.js +7 -5
  31. package/dist/grade/command-inspect.js +2 -1
  32. package/dist/grade/command-run.js +39 -0
  33. package/dist/grade/grade.js +3 -1
  34. package/dist/grade/markdown.js +4 -4
  35. package/dist/grade/pipeline-state.js +8 -6
  36. package/dist/grade/plan.js +8 -6
  37. package/dist/grade/run.js +307 -0
  38. package/dist/grade/target-discovery.js +1 -1
  39. package/dist/grade/targets.js +44 -22
  40. package/dist/kata/command.js +54 -9
  41. package/dist/register/approach.js +16 -0
  42. package/dist/register/core.js +2 -0
  43. package/dist/register/create-commands.js +57 -7
  44. package/dist/register/deliverable-target.js +215 -0
  45. package/dist/register/events.js +4 -0
  46. package/dist/register/external-project.js +18 -7
  47. package/dist/register/item.js +8 -0
  48. package/dist/register/views.js +3 -0
  49. package/dist/review/grade.js +19 -17
  50. package/dist/shared/agent-plan.js +1 -0
  51. package/dist/shared/git.js +3 -2
  52. package/dist/shared/lefthook-scaffold.js +5 -22
  53. package/dist/shared/markdownlint-scaffold.js +67 -0
  54. package/dist/shared/provider-scaffold.js +7 -5
  55. package/dist/shared/slidev-scaffold.js +102 -0
  56. package/dist/shared/specdojo-config.js +9 -3
  57. package/dist/specdojo.js +5 -1
  58. package/docs/ja/specdojo/exec-templates/xep-register-template.md +5 -4
  59. package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +2 -2
  60. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +2 -2
  61. package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +2 -2
  62. package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +2 -2
  63. package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +2 -2
  64. package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +2 -2
  65. package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +2 -2
  66. package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +2 -2
  67. package/docs/ja/specdojo/exec-templates/xrp-template.md +2 -2
  68. package/docs/ja/specdojo/guides/exec-config-guide.md +81 -19
  69. package/docs/ja/specdojo/guides/exec-operation-guide.md +4 -0
  70. package/docs/ja/specdojo/guides/kata-guide.md +108 -1
  71. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +6 -6
  72. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +3 -1
  73. package/docs/ja/specdojo/guides/quick-start-guide.md +22 -2
  74. package/docs/ja/specdojo/guides/register-operation-guide.md +2 -0
  75. package/docs/ja/specdojo/guides/remote-host-development-guide.md +15 -1
  76. package/docs/ja/specdojo/guides/review-guide.md +2 -2
  77. package/docs/ja/specdojo/guides/ryu-guide.md +12 -0
  78. package/docs/ja/specdojo/references/command-reference.md +178 -62
  79. package/docs/ja/specdojo/references/specdojo-config-reference.md +31 -8
  80. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +28 -22
  81. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +17 -1
  82. package/docs/specdojo/schemas/v1/grade-pipeline-state.schema.yaml +1 -1
  83. package/docs/specdojo/schemas/v1/register-events.schema.yaml +2 -0
  84. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +33 -1
  85. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +16 -3
  86. package/package.json +5 -5
  87. package/templates/antigravity/orchestrator.md +4 -4
  88. package/templates/claude/README.md +2 -0
  89. package/templates/claude/agents/specdojo-orchestrator.md +4 -4
  90. package/templates/codex/README.md +38 -9
  91. package/templates/codex/agents/codex-executor.toml +1 -1
  92. package/templates/codex/agents/codex-expert-executor.toml +1 -1
  93. package/templates/codex/agents/codex-expert-review-executor.toml +1 -1
  94. package/templates/codex/agents/codex-review-executor.toml +1 -1
  95. package/templates/codex/agents/specdojo-orchestrator.toml +5 -5
  96. package/templates/codex/orchestrator.md +4 -4
  97. package/templates/devcontainer/devcontainer.json +1 -0
  98. package/templates/init-agent-members.yaml +131 -16
  99. package/templates/opencode/README.md +118 -14
  100. package/templates/opencode/agents/specdojo-orchestrator.md +5 -5
  101. package/templates/opencode/opencode.json +25 -0
@@ -38,16 +38,16 @@ project の解決順序と設定は [遂行の技活用ガイド](../guides/waza
38
38
 
39
39
  ## 2. init / config / project
40
40
 
41
- | コマンド | 用途 | 例 |
42
- | ------------------------ | ----------------------------------------------------------- | ------------------------------------------- |
43
- | `init` | project から agent 実行までを質問式で初期設定する | `specdojo init` |
44
- | `config init` | `specdojo.config.json` と `.gitignore` を個別に用意する | `specdojo config init` |
45
- | `config migrate-members` | agent 定義を保護設定へ移す | `specdojo config migrate-members --dry-run` |
46
- | `config scaffold` | provider、VS Code ワークスペース、Git hook を個別に配置する | `specdojo config scaffold --lefthook` |
47
- | `project list` | 登録済み project を表示する | `specdojo project list` |
41
+ | コマンド | 用途 | 例 |
42
+ | ------------------------ | ------------------------------------------------------------------- | ------------------------------------------- |
43
+ | `init` | project から agent 実行までを質問式で初期設定する | `specdojo init` |
44
+ | `config init` | `specdojo.config.json` と `.gitignore` を個別に用意する | `specdojo config init` |
45
+ | `config migrate-members` | agent 定義を保護設定へ移す | `specdojo config migrate-members --dry-run` |
46
+ | `config scaffold` | provider、VS Code ワークスペース、Git hook、Slidev を個別に配置する | `specdojo config scaffold --slidev` |
47
+ | `project list` | 登録済み project を表示する | `specdojo project list` |
48
48
 
49
49
  `init` は対話できる端末で、project ID と名前、register、人の nickname と表示名、複数指定可能な
50
- provider、exec、Dev Container、Git hook の順に質問します。Dev Container を選んだ場合だけ、続けて `minimal` / `recommended` / `full` の preset を質問します(既定は `recommended`)。Git hook は既定では作りません。成果物カタログは対話では質問せず、`--catalog <size>` を
50
+ provider、exec、Dev Container、Git hook、Slidev の順に質問します。Dev Container を選んだ場合だけ、続けて `minimal` / `recommended` / `full` の preset を質問します(既定は `recommended`)。Git hook は既定では作りません。Slidev の質問は `full` を選んだ場合だけ既定が「はい」、それ以外は「いいえ」です。成果物カタログは対話では質問せず、`--catalog <size>` を
51
51
  明示した場合にだけ作成します。既存ファイルは上書きせず、スキップしたパスを表示します。`--dry-run` は
52
52
  予定だけを表示し、ファイルや `package.json` を変更しません。各回答は質問の直後に検証され、誤りの理由を
53
53
  表示して同じ質問だけをやり直します。それまでの回答は保持されます。`--exec` を選んだのに provider が
@@ -56,24 +56,30 @@ provider、exec、Dev Container、Git hook の順に質問します。Dev Contai
56
56
 
57
57
  非対話環境では質問せず、次の主要オプションと既定値を使います。
58
58
 
59
- | オプション | 用途 | 既定値 |
60
- | ------------------------------ | ------------------------------------------------------------------------- | --------------- |
61
- | `--yes` | 質問せず既定値と指定済みオプションで実行する | - |
62
- | `--project <id>` | project ID | `prj-0001` |
63
- | `--name <name>` | project の表示名 | `My Project` |
64
- | `--no-register` | register を作らない | register を作る |
65
- | `--nickname <nickname>` | 人の名簿に書く nickname | `owner` |
66
- | `--display-name <name>` | 人の名簿に書く表示名 | `Project Owner` |
67
- | `--provider <names>` | provider をカンマ区切りで指定する | `codex` |
68
- | `--exec` | executor / reporter の名簿と起動設定を作る | 作らない |
69
- | `--catalog <size>` | `small` / `medium` / `large` の成果物カタログを作る(対話では質問しない) | 作らない |
70
- | `--devcontainer` | 選んだ provider の Dev Container を作る | 作らない |
71
- | `--lefthook` | commit 前の文書・SpecDojo 検査を行う Git hook を作る | 作らない |
72
- | `--devcontainer-preset <name>` | Dev Container の preset(`minimal` / `recommended` / `full`)を選ぶ | `recommended` |
73
- | `--workspace-name <name>` | Dev Container 内で使う親ディレクトリ名 | ホスト側の親名 |
74
- | `--dry-run` | 作成・変更予定だけを表示する | 書き込む |
59
+ | オプション | 用途 | 既定値 |
60
+ | ------------------------------ | ------------------------------------------------------------------------- | --------------------- |
61
+ | `--yes` | 質問せず既定値と指定済みオプションで実行する | - |
62
+ | `--project <id>` | project ID | `prj-0001` |
63
+ | `--name <name>` | project の表示名 | `My Project` |
64
+ | `--no-register` | register を作らない | register を作る |
65
+ | `--nickname <nickname>` | 人の名簿に書く nickname | `owner` |
66
+ | `--display-name <name>` | 人の名簿に書く表示名 | `Project Owner` |
67
+ | `--provider <names>` | provider をカンマ区切りで指定する | `codex` |
68
+ | `--exec` | executor / reporter の名簿と起動設定を作る | 作らない |
69
+ | `--catalog <size>` | `small` / `medium` / `large` の成果物カタログを作る(対話では質問しない) | 作らない |
70
+ | `--devcontainer` | 選んだ provider の Dev Container を作る | 作らない |
71
+ | `--lefthook` | commit 前の文書・SpecDojo 検査を行う Git hook を作る | 作らない |
72
+ | `--slidev` | Slidev 本体と kata 用の整形・検査設定を追加する | `full` の場合だけ追加 |
73
+ | `--no-slidev` | `full` を選んだ場合も Slidev の追加を解除する | - |
74
+ | `--devcontainer-preset <name>` | Dev Container の preset(`minimal` / `recommended` / `full`)を選ぶ | `recommended` |
75
+ | `--workspace-name <name>` | Dev Container 内で使う親ディレクトリ名 | ホスト側の親名 |
76
+ | `--dry-run` | 作成・変更予定だけを表示する | 書き込む |
75
77
 
76
78
  `--devcontainer-preset none` は後方互換のため受け付け、`minimal` と同じ構成として扱います。
79
+ `init --yes --devcontainer --devcontainer-preset full` は Slidev も追加します。Dev Container の
80
+ `full` は VS Code 拡張 `antfu.slidev` も含み、`minimal` / `recommended` は含みません。
81
+ 拡張の選択とリポジトリの npm・整形設定は独立しているため、`--no-slidev` は拡張を外しません。
82
+ `devcontainer scaffold --preset full` 単体では npm・整形設定を変更しません。
77
83
 
78
84
  `init` が作る `.specdojo/agent-members.yaml` と `.specdojo/exec-defaults.yaml` は、選択した
79
85
  provider だけを含みます。親 runner の検証は、対応する `package.json` の npm script が存在する
@@ -95,7 +101,7 @@ provider 設定、登録簿作成の順に次のコマンドを案内します
95
101
  書き込まず、予定の内容だけを表示します。`config scaffold` の `--provider` には
96
102
  `antigravity`、`claude`、`codex`、`copilot`、`opencode` を指定でき、`--dry-run` と `--force` も利用できます。
97
103
 
98
- `package.json` がある場合、provider ごとのオーケストレーター起動スクリプトも追加します。Claude Code は `orch:opus`・`orch:sonnet`、Codex は `orch:sol`(`gpt-5.6-sol`)・`orch:terra`(`gpt-5.6-terra`)、Antigravity は `orch:flash`(`gemini-3.8-flash-high`)、OpenCode は `orch:opencode` です。既存のスクリプトは `--force` を付けても上書きしません。
104
+ `package.json` がある場合、provider ごとのオーケストレーター起動スクリプトも追加します。Claude Code は `orch:opus`・`orch:sonnet`、Codex は `orch:sol`(`gpt-6.1-sol`)・`orch:luna`(`gpt-6-luna`)、Antigravity は `orch:flash`(`gemini-3.8-flash-high`)、OpenCode は `orch:opencode` です。既存のスクリプトは `--force` を付けても上書きしません。
99
105
 
100
106
  `antigravity` に限り `--global` を指定すると、`~/.gemini/antigravity-cli/settings.json` へ SpecDojo 用の permission rule を追記します。既存キー・既存 rule は保持し、実書き込み前に timestamp 付きバックアップを作ります。`--global` を省略した通常実行はユーザーディレクトリへ触れません。適用前は次の dry-run で追加 rule を確認してください。
101
107
 
@@ -106,8 +112,65 @@ specdojo config scaffold --provider antigravity --global
106
112
 
107
113
  `--force` はリポジトリ内の scaffold ファイルだけを上書きし、グローバル設定の既存項目は上書きしません。従来の `exec scaffold --provider antigravity` でも同じ `--global` / `--dry-run` の挙動を利用できます。
108
114
 
109
- `config scaffold --lefthook` は、利用リポジトリに `lefthook.yml`、`.markdownlint.jsonc`、
110
- `.markdownlintignore`、依存なしで起動できる `tools/install-lefthook.mjs` と
115
+ `config scaffold --slidev` は、`@slidev/cli`・`prettier-plugin-slidev`・`prettier` の不足する
116
+ devDependencies を表示してから `package.json` へ追加し、未作成なら `.prettierrc` と
117
+ `.markdownlintignore`、基本設定の `.markdownlintrc`、VS Code 向けの `.markdownlint-cli2.yaml` を作ります。
118
+ 既存の dependencies / devDependencies の同名項目は維持し、
119
+ `package.json` がない場合は追加例だけを表示します。依存のインストールは利用者が `npm install` で行います。
120
+
121
+ ```bash
122
+ specdojo init --yes --slidev
123
+ # 初期設定済みのリポジトリに追加する場合
124
+ specdojo config scaffold --slidev --dry-run
125
+ specdojo config scaffold --slidev
126
+ npm install
127
+ ```
128
+
129
+ 既定で整形・検査設定の対象にするのは、次の Slidev 用命名の kata だけです。
130
+
131
+ - `docs/ja/specdojo/samples/**/*-slidev-sample.md`
132
+ - `docs/ja/specdojo/templates/**/*-slidev-template.md`
133
+
134
+ Prettier の overrides 内で `parser: slidev` と plugin を指定します。同じパスを
135
+ `.markdownlint-cli2.yaml` の `overrides` では Slidev 用の規則で検査し、`.markdownlintignore` では
136
+ markdownlint-cli の対象外にします。通常の Markdown には基本設定を当てます。
137
+ 既存の `lsd-sample.md` など別名のスライドは、実際のパスを Prettier の `files`、CLI2 の `filter`、
138
+ ignore の 3 か所にそろえて追加してください。
139
+ markdownlint-cli2 は最初に一致した override だけを使うため Slidev 用を先頭に、Prettier は後の一致が
140
+ 優先されるため Slidev 用を末尾に置きます。CLI2 の追加例は次の形です。
141
+
142
+ ```yaml
143
+ config:
144
+ extends: .markdownlintrc
145
+ overrides:
146
+ - filter:
147
+ - docs/ja/specdojo/samples/**/*-slidev-sample.md
148
+ - docs/ja/specdojo/templates/**/*-slidev-template.md
149
+ combine: merge
150
+ config:
151
+ MD001: false
152
+ MD022: false
153
+ MD025: false
154
+ MD031: false
155
+ MD032: false
156
+ ```
157
+
158
+ スライドごとの見出しレベル・H1 と、ページ区切りやページごとの frontmatter に隣接する見出し・
159
+ コード・リストを許すため、この 5 規則を外します。ほかの規則は基本設定を引き継ぎます。
160
+ `.prettierrc`(別拡張子や `prettier.config.*`、`package.json` の `prettier` 設定を含む)と
161
+ `.markdownlintignore`、既存の `.markdownlint.*`・`.markdownlintrc`・`.markdownlint-cli2.*` は
162
+ `--force` を付けても保持し、手で統合する設定例を表示します。既存の設定と競合する場合は新規設定も
163
+ 自動作成せず、不足する設定と移行方法を表示します。
164
+ `--lefthook --slidev` の同時指定では、新規の ignore に agent 定義とスライドの両方の除外を含めます。
165
+ `--dry-run` は内容を表示するだけで書き込みません。指定しなければ Slidev の依存・設定は追加しません。
166
+
167
+ テーマと活動固有のコンポーネント・素材は利用者が用意します。kata の sample を
168
+ `./node_modules/.bin/slidev build <sample.md> --out "$PWD/tmp/slidev-dist"` で検証する手順と、
169
+ テーマ・部品の配置方法は [[specdojo:kata-guide|実践の型活用ガイド]] の「Slidev の kata を検証する」を参照してください。
170
+
171
+ `config scaffold --lefthook`(`init --lefthook` も同様)は、利用リポジトリに `lefthook.yml`、
172
+ `.markdownlintrc`、`.markdownlint-cli2.yaml`、`.markdownlintignore`、
173
+ 依存なしで起動できる `tools/install-lefthook.mjs` と
111
174
  `tools/specdojo-pre-commit.mjs` を生成します。pre-commit では staged の Markdown と YAML だけを
112
175
  Prettier で整形し、staged の Markdown だけを markdownlint で検査します。
113
176
  また、`.specdojo/specdojo.config.json` の `project_register_path` 配下に staged の変更がある project では
@@ -132,6 +195,30 @@ devDependencies は `--force` を指定しても保持します。`package.json`
132
195
  `node tools/install-lefthook.mjs` を実行してください。hook 内から Git を呼ぶ入口は `GIT_DIR` などの
133
196
  repository-local 環境変数を除いてから staged files を調べます。
134
197
 
198
+ 生成する設定と道具の対応は次のとおりです。CLI2 本体は開発依存に追加しません。
199
+
200
+ | 設定 | 読む道具と役割 |
201
+ | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
202
+ | `.markdownlintrc` | markdownlint-cli(commit hook と exec run の result 検査)が読む基本設定。`MD013: false` などを指定した、先頭が `{` の JSON |
203
+ | `.markdownlint-cli2.yaml` | VS Code の markdownlint 拡張と markdownlint-cli2 用。`config.extends` で `.markdownlintrc` を読み、`overrides` でファイル別に調整 |
204
+ | `.markdownlintignore` | markdownlint-cli 用。agent 定義や Slidev の kata を hook・result 検査の対象外にする。CLI2 と VS Code の拡張は読まない |
205
+
206
+ 以前の scaffold が生成した `.markdownlint.jsonc` などが残っていると、VS Code で CLI2 の
207
+ `overrides` が効きません。既存リポジトリは次の手順で移行してください。
208
+
209
+ 1. `.markdownlint.jsonc` / `.json` / `.yaml` / `.yml` の既存規則を `.markdownlintrc` に移します。
210
+ YAML は JSON に変換し、コメントを除いて、ファイルの先頭を `{` にします。
211
+ 既存の `.markdownlintrc` があれば規則を統合します。
212
+ 2. 移した旧 `.markdownlint.*` を取り除きます。対象ファイルの親ディレクトリにある設定も確認してください。
213
+ 3. 既存の `.markdownlint-cli2.*` があればそのファイルへ、なければ `.markdownlint-cli2.yaml` へ、
214
+ 上例の `config.extends: .markdownlintrc` を設定します。相対パスは CLI2 設定ファイルからの位置に合わせます。
215
+ `--slidev` が表示した override は先頭に統合します。
216
+ 4. Prettier の Slidev override は末尾へ置き、`.markdownlintignore` と CLI2 の `filter` を同じ glob にそろえます。
217
+ VS Code でスライドと通常の文書を開き、hook と result 検査でも基本設定が効くことを確認してください。
218
+
219
+ scaffold は `--force` でもこの移行を自動実行しません。Slidev のビルド・表示の検証手順は
220
+ [[specdojo:kata-guide|実践の型活用ガイド]] を参照してください。
221
+
135
222
  `config scaffold --workspace` は、`.specdojo/specdojo.config.json` の `repos` 宣言から VS Code のマルチルートワークスペース(`<project-id>.code-workspace`)をリポジトリルートに生成します。`folders` にはプロジェクトリポジトリ(`.`)と各プロダクトリポジトリ(`repos[].path`)を宣言順に並べ、別リポジトリ構成でも 1 つの VS Code ウィンドウでプロジェクトとプロダクトを同時に開けます。`--project <id>` で対象 project を指定でき、省略時は `current_project` を使います。既存のファイルは `--force` を指定しない限り上書きしません。`repos` が宣言されていない project ではエラーになります。`--dry-run` は書き込まず予定の内容だけを表示します。
136
223
 
137
224
  ```bash
@@ -148,13 +235,13 @@ specdojo config scaffold --workspace --force
148
235
 
149
236
  `kata` は、利用リポジトリで作成・上書きした型(Kata)と npm package から参照中の型を確認・取得します。対象種別は rulebook / standard / recipe / sample / template です。同じ正準パスにファイルがある場合は利用リポジトリ側を優先します。`kata_authority` の kata は `docs/ja/specdojo/<種類>s/<kata_authority>/` から解決し、`kata list` と `kata show` にも表示します。0.4.4 のあいだは旧 `docs/ja/kata/<種類>s/` も読み、新配置への移動案内を標準エラーへ出します。新旧に同じ ID があれば新配置を優先します。
150
237
 
151
- | コマンド | 用途 | 例 |
152
- | ---------------- | ------------------------------------------------------- | ------------------------------------------------ |
153
- | `kata list` | kata を解決元と eject 可否つきで一覧表示 | `specdojo kata list --all` |
154
- | `kata show <id>` | 解決順序に従って kata の内容を表示 | `specdojo kata show specdojo:pjr-rulebook` |
155
- | `kata status` | 参照中 / eject 済みと package 原本との差分を表示 | `specdojo kata status --kind template` |
156
- | `kata eject` | package の 1 ファイルを利用リポジトリの正準パスへコピー | `specdojo kata eject --id specdojo:pjr-rulebook` |
157
- | `kata install` | eject 可能な全種別を利用リポジトリへコピー | `specdojo kata install --all --dry-run` |
238
+ | コマンド | 用途 | 例 |
239
+ | ---------------- | ------------------------------------------------ | ------------------------------------------------ |
240
+ | `kata list` | kata を解決元と eject 可否つきで一覧表示 | `specdojo kata list --all` |
241
+ | `kata show <id>` | 解決順序に従って kata の内容を表示 | `specdojo kata show specdojo:pjr-rulebook` |
242
+ | `kata status` | 参照中 / eject 済みと package 原本との差分を表示 | `specdojo kata status --kind template` |
243
+ | `kata eject` | package の kata と付属ファイルを正準パスへコピー | `specdojo kata eject --id specdojo:pjr-rulebook` |
244
+ | `kata install` | eject 可能な全種別を利用リポジトリへコピー | `specdojo kata install --all --dry-run` |
158
245
 
159
246
  主要オプション:
160
247
 
@@ -171,6 +258,10 @@ specdojo config scaffold --workspace --force
171
258
 
172
259
  `eject` と `install --all` は既存ファイルを `--force` なしで上書きせず、`skip` として表示します。CLI と同じバージョンで使う必要がある `exec-templates` と `schemas` は個別 eject の対象外で、指定すると参照固定である旨を表示して終了コード 1 で終わります。`install --all` は docs サイト配信やオフライン運用向けの明示的な全量取得であり、通常のセットアップ導線では使用しません。
173
260
 
261
+ 付属ファイルは一覧の kata に数えず、`eject`・`install --all` で本体と一緒にコピーします。
262
+ 付属ファイルだけの差分も、eject 済みの親 kata の `modified` に含めます。対象形式と付属ファイルの
263
+ 命名・配置・dry-run の詳細は [[specdojo:kata-guide|実践の型活用ガイド]] の「kata の付属ファイル」を参照してください。
264
+
174
265
  ## 3. catalog / deliverable
175
266
 
176
267
  `catalog` は成果物カタログ(`dct-*.yaml`)を扱います。
@@ -382,34 +473,46 @@ specdojo schedule strategy generate \
382
473
 
383
474
  主要オプション:
384
475
 
385
- | オプション | 用途 | 対象 |
386
- | ------------------------- | ------------------------------------------------------------------- | ------------------------------------------------ |
387
- | `--to <PJR-ID>` | 移動先の PJR-ID を指定する | `renumber` |
388
- | `--registered <datetime>` | 起票日時(タイムゾーン付き RFC 3339)。省略時は実行時刻 | `add` |
389
- | `--completed <datetime>` | 完了・却下日時(タイムゾーン付き RFC 3339)。省略時は実行時刻 | `close` / `reject` |
390
- | `--by <actor>` | 名簿または予約一覧の actor を追記型 event に記録する | `add` / 更新 / 遷移コマンド |
391
- | `--reason <text>` | event の理由を記録(`wait` では `block_reason` も更新) | `add` / 更新 / 遷移コマンド |
392
- | `--conclusion <text>` | 終端時の結論を記録・更新(`update` では `-` で削除) | `add` / `update` / 終端コマンド |
393
- | `--block-reason <text>` | `waiting` の理由を更新(`-` で削除) | `update` |
394
- | `--approach <approach>` | 個票の進め方を指定(`update` では `-` で削除) | `add` / `update` |
395
- | `--target <doc-id>` | 対象文書 ID を指定(繰り返し可、`update` では `-` で削除) | `add` / `update` |
396
- | `--source <ref>` | kata authoring の手本を指定(繰り返し可、`update` では `-` で削除) | `add` / `update` |
397
- | `--topic <slug>` | 個票ファイル名と文書 ID の論点部分を指定・更新する | `add` / `update` |
398
- | `--commit` | `register lifecycle` 枠内で記帳・再生成・commitを行う | `add` / `update` / `renumber` / 遷移 |
399
- | `-m, --message <message>` | `--commit` のcommitメッセージを上書きする | `add` / `update` / `renumber` / 遷移 |
400
- | `--dry-run` | 書き込みを行わず変更対象を表示する | `add` / `update` / `renumber` / 遷移 / `migrate` |
401
- | `--since <date>` | 対象コミットの開始日(`YYYY-MM-DD`、当日を含む) | `history` |
402
- | `--until <date>` | 対象コミットの終了日(`YYYY-MM-DD`、当日を含む) | `history` |
403
- | `--id <PJR-ID...>` | 出力する項目を限定する(空白・カンマ区切りで複数可) | `history` |
404
- | `--status-only` | 追加・削除・状態遷移だけを出力する | `history` |
405
- | `--limit <count>` | 走査するコミット数の上限 | `history` |
406
- | `--json` | イベントを JSON で出力する | `history` |
476
+ | オプション | 用途 | 対象 |
477
+ | ---------------------------- | ------------------------------------------------------------------- | ------------------------------------------------ |
478
+ | `--to <PJR-ID>` | 移動先の PJR-ID を指定する | `renumber` |
479
+ | `--registered <datetime>` | 起票日時(タイムゾーン付き RFC 3339)。省略時は実行時刻 | `add` |
480
+ | `--completed <datetime>` | 完了・却下日時(タイムゾーン付き RFC 3339)。省略時は実行時刻 | `close` / `reject` |
481
+ | `--by <actor>` | 名簿または予約一覧の actor を追記型 event に記録する | `add` / 更新 / 遷移コマンド |
482
+ | `--reason <text>` | event の理由を記録(`wait` では `block_reason` も更新) | `add` / 更新 / 遷移コマンド |
483
+ | `--conclusion <text>` | 終端時の結論を記録・更新(`update` では `-` で削除) | `add` / `update` / 終端コマンド |
484
+ | `--block-reason <text>` | `waiting` の理由を更新(`-` で削除) | `update` |
485
+ | `--approach <approach>` | 個票の進め方を指定(`update` では `-` で削除) | `add` / `update` |
486
+ | `--target <doc-id>` | 対象文書 ID を指定(繰り返し可、`update` では `-` で削除) | `add` / `update` |
487
+ | `--target-path <path>` | 成果物のリポジトリ相対パス(`update` は `-` で削除) | `add` / `update` |
488
+ | `--target-rulebook <doc-id>` | 成果物の rulebook ID(`update` は `-` で削除) | `add` / `update` |
489
+ | `--source <ref>` | kata authoring の手本を指定(繰り返し可、`update` では `-` で削除) | `add` / `update` |
490
+ | `--topic <slug>` | 個票ファイル名と文書 ID の論点部分を指定・更新する | `add` / `update` |
491
+ | `--commit` | `register lifecycle` 枠内で記帳・再生成・commitを行う | `add` / `update` / `renumber` / 遷移 |
492
+ | `-m, --message <message>` | `--commit` のcommitメッセージを上書きする | `add` / `update` / `renumber` / 遷移 |
493
+ | `--dry-run` | 書き込みを行わず変更対象を表示する | `add` / `update` / `renumber` / 遷移 / `migrate` |
494
+ | `--since <date>` | 対象コミットの開始日(`YYYY-MM-DD`、当日を含む) | `history` |
495
+ | `--until <date>` | 対象コミットの終了日(`YYYY-MM-DD`、当日を含む) | `history` |
496
+ | `--id <PJR-ID...>` | 出力する項目を限定する(空白・カンマ区切りで複数可) | `history` |
497
+ | `--status-only` | 追加・削除・状態遷移だけを出力する | `history` |
498
+ | `--limit <count>` | 走査するコミット数の上限 | `history` |
499
+ | `--json` | イベントを JSON で出力する | `history` |
407
500
 
408
501
  `register add` は個票 Frontmatter の `registered_at`(起票日時)を、`register close` / `register reject` は `completed_at`(完了・却下日時)を自動記入します。値は UTC の RFC 3339・秒精度(例: `2026-08-09T14:08:51Z`)で、OS / コンテナの `TZ` 環境変数には依存しません。`register reopen` は `completed_at` を削除します。
409
502
 
410
503
  `register` の `--by` は、project の `pm-members.yaml` にある人の nickname、`.specdojo/agent-members.yaml` にある agent の nickname または alias、予約 actor の `SpecDojo`・`specdojo-orchestrator`・`night-orchestrator` だけを受け付けます。agent alias は実体名で event に記録し、未知の値は書き込み前に拒否します。省略時は `SpecDojo` です。決定・承認では `PO` などの Role code や予約 actor ではなく、本人の nickname を指定します。
411
504
 
412
- `--approach` を指定する場合、通常は `--target` が 1 件だけ必須です。成果物を作成・修正する approach の対象は成果物カタログの doc id で解決するため、まだ文書がない成果物も指定できます。kata maintenance の対象は文書索引で解決し、approach に対応する kata 種別との一致も書き込み前に検証します。kata authoring は `--target` を新しい kata ID、`--source` を 0 件以上の読み取り専用の手本とします。互換性のため、2 個目以降の `--target` も `--source` と同じ手本として扱います。
505
+ `--approach` を指定する場合、通常は `--target` が 1 件だけ必須です。成果物を作成・修正する approach の対象は、成果物カタログを優先して doc id を解決します。カタログがなくても、既存文書は文書索引と frontmatter から、新規文書は明示したパスと rulebook から解決できます。kata maintenance の対象は文書索引で解決し、approach に対応する kata 種別との一致も書き込み前に検証します。kata authoring は `--target` を新しい kata ID、`--source` を 0 件以上の読み取り専用の手本とします。互換性のため、2 個目以降の `--target` も `--source` と同じ手本として扱います。
506
+
507
+ カタログなしで使える成果物の approach は `fully-guided`・`recipe-guided`・`freeform`・`retrofit`・`bootstrap`・`finalize`・`bootstrap-finalize` です。`cross-deliverable-dedup` はカタログが必要です。
508
+
509
+ - 新規文書には `--target-path <リポジトリ相対パス>` と `--target-rulebook <rulebook-id>` を指定します。個票の `target_path` と `target_rulebook` に保存されます。既存文書は `--target` の ID を索引で引き、パスと `specdojo.rulebook` を使います。明示指定と既存文書が矛盾した場合は停止します。
510
+ - パスはリポジトリ外、外を指すシンボリックリンク、別の ID を持つ既存ファイルを受け付けません。更新時も同じ検証を行い、`--target-path -`・`--target-rulebook -` で各指定を削除できます。
511
+ - recipe・sample・template は rulebook frontmatter から解決します。`not-needed` の型は plan に列挙しません。`fully-guided` に必要な一式や `recipe-guided` の recipe がないときは、不足した型を示して起票を拒否します。
512
+ - `bootstrap` はパスと新しい rulebook ID の両方、および設定の `kata_authority` が必須です。既存 rulebook は拒否します。`<authority>:<stem>-rulebook` から `<authority>:<stem>-recipe`・`-sample`・`-template` を導出し、`docs/ja/specdojo/<kind>s/<authority>/<stem>-<kind>.md` の未作成候補を plan に載せます。既存 ID・パスとの衝突も拒否します。
513
+ - `finalize`・`bootstrap-finalize` は未作成の成果物を拒否します。個票の完了条件をチェック表にし、前者は成果物、後者は成果物と frontmatter から辿った kata 一式を確定対象にします。
514
+ - カタログなしの plan は、カタログの `done_criteria` がないことを明示し、個票の完了条件と rulebook を使います。`retrofit` の実装調査入力は個票にパスを明記します。
515
+ - カタログ設定済みで対象が未登録の場合、パスと rulebook を両方明示した場合だけカタログなしと同じ解決を使います。未指定なら従来のエラーで停止します。カタログにある対象ではカタログの宣言を優先します。
413
516
 
414
517
  `item_type: note` は `open` のまま更新する記録です。`register close` / `register reject` / `register defer` は終了コード 1 で拒否し、対応・回答・判断が必要な場合は `todo` / `question` / `decision` など目的に合う別の `item_type` で起票するよう案内します。本文の追記や修正には `register update` を使用できます。
415
518
 
@@ -433,13 +536,13 @@ kata authoring は register 専用です。Schedule の task は対象成果物
433
536
 
434
537
  別 project への `register add` は `--commit` が必須です。対象 project の登録簿に未 commit 変更がある場合、または統合ブランチがローカルに存在しない場合は、何も書き込まず終了コード 1 で停止します。元の worktree とブランチは変更しません。`close`、`reject` など別 project の状態遷移は受け付けず、対象 project の worktree での実行を案内します。
435
538
 
436
- 別リポジトリへの起票も `--commit` が必須です。相手のリポジトリ、`node_modules/.bin/specdojo`、0.4.2 以上の版のいずれかを確認できない場合は、相手を変更せず停止します。相手の起票が失敗した場合は相手の標準出力・標準エラー出力と終了コードをそのまま引き継ぎ、push は行いません。外部 project の `close` などの状態遷移は委譲しないため、案内された相手のリポジトリで実行してください。
539
+ 別リポジトリへの起票も `--commit` が必須です。起動する CLI は相手の `node_modules/.bin/specdojo` を優先します。これがなく、相手の `package.json` の `name` が `specdojo` の場合は、呼び出し元と同じ Node.js で `node <相手>/dist/specdojo.js` を起動します。SpecDojo 自身の clone では、先に `npm install` と `npm run build` を実行してください。`dist/specdojo.js` がない場合は `npm run build` を案内して停止します。相手のリポジトリ、起動する CLI、0.4.2 以上の版のいずれかを確認できない場合は、相手を変更せず停止します。相手の起票が失敗した場合は相手の標準出力・標準エラー出力と終了コードをそのまま引き継ぎ、push は行いません。外部 project の `close` などの状態遷移は委譲しないため、案内された相手のリポジトリで実行してください。
437
540
 
438
541
  一覧・派生ビューの「登録日」「完了日」は、保存した日時を config の `run.register_date_timezone`(IANA タイムゾーン名、既定 `UTC`)へ変換して導出する表示値です。
439
542
 
440
543
  `register migrate` は旧形式の登録簿データを現行形式へ移す一度限りの移行コマンドです。追跡対象だった `pjr-index.md` の表を個票 Frontmatter へ移し、旧日時を UTC へ変換し、個票内の `register_events` を `events/pjr-XXXX.yaml` へ分離します。イベントがまだない項目は、利用可能な Git 履歴を項目別イベントファイルへ変換します。event ID は commit・項目 ID・変更内容から決定的に生成するため、再実行で重複しません。
441
544
 
442
- `register history` は `events/pjr-XXXX.yaml` を読み、個票単位の追加(`added`)と変更(`updated`)を発生順に出力します。event 導入前または未移行の期間だけ Git 履歴を読み、削除(`removed`)を含む従来の履歴と統合します。event は発生日時・actor・action・reason・遷移前後状態・変更フィールドを保持するため、複数遷移を1コミットへまとめても粒度を失いません。比較対象は登録項目一覧の列と `block_reason`、`approach`、`targets`、`derived_from` です。
545
+ `register history` は `events/pjr-XXXX.yaml` を読み、個票単位の追加(`added`)と変更(`updated`)を発生順に出力します。event 導入前または未移行の期間だけ Git 履歴を読み、削除(`removed`)を含む従来の履歴と統合します。event は発生日時・actor・action・reason・遷移前後状態・変更フィールドを保持するため、複数遷移を1コミットへまとめても粒度を失いません。比較対象は登録項目一覧の列と `block_reason`、`approach`、`targets`、`sources`、`target_path`、`target_rulebook`、`derived_from` です。
443
546
 
444
547
  各書き込みコマンドは現在値を個票へ、event を項目別イベントファイルへ反映します。同じ現在値になる操作の再実行では event を追加しません。`register build` は個票とイベントファイルの対応、event の schema、ID 一意性、時刻順、直前イベント参照、状態連鎖、最新 event と現在値の一致を検証します。
445
548
 
@@ -654,11 +757,12 @@ specdojo exec trial adopt --project prj-0001 --comparison <comparison-id> --tria
654
757
 
655
758
  `grade` は kata(rulebook / recipe / sample / template)または成果物を、review と同じ共通 viewpoint・category rubric で継続評価します。agent に直接ファイル探索やスコア計算をさせず、plan 生成と反映を分離します。
656
759
 
657
- v0.3.0 の `grade` は試験的な機能です。npm package で利用できるのは `grade list` / `plan` / `apply` / `validate` / `result` などの部品で、通しの実行を担う `grade run` はありません。`tools/grade/run-per-document.sh` は SpecDojo 本体リポジトリの開発用であり、npm package には含まれません。成果物を `--target deliverable` で評価するには、対象 project に `catalog_path` を設定する必要があります。
760
+ `grade run` は npm package から利用でき、`list` と同じ対象選択、文書ごとの plan 生成、agent 実行、marker の機械変換と `apply` を単段で実行します。成果物を `--target deliverable` で評価するには、対象 project に `catalog_path` を設定する必要があります。`viewpoints_path` 未設定時は同梱の `specdojo:pm-review-viewpoints` を使います。
658
761
 
659
762
  | コマンド | 用途 |
660
763
  | ------------------------ | -------------------------------------------------------------- |
661
764
  | `grade list` | 選択した文書のパスを1行1件で出力し、plan は保存しない |
765
+ | `grade run` | 文書ごとに評価と反映を実行し、同じ run を再開する |
662
766
  | `grade plan` | 1文書ごとに executor / reporter の評価 plan を保存する |
663
767
  | `grade apply` | executor の申告を GradeSubmission へ機械変換して正本を反映する |
664
768
  | `grade translation-plan` | 正本の英語 finding から日本語表示用の翻訳 plan を作る |
@@ -668,6 +772,10 @@ v0.3.0 の `grade` は試験的な機能です。npm package で利用できる
668
772
  | `grade migrate` | インライン grade / finding をサイドカーへ一括移行する |
669
773
 
670
774
  ```bash
775
+ specdojo grade run --target kata --kind rulebook --run-id quality-check --dry-run
776
+ specdojo grade run --target kata --path <document.md> --run-id quality-check --by <executor-nickname>
777
+ # 同じコマンドを再実行すると完了済み文書を飛ばし、未完了文書から再開する
778
+ specdojo grade run --target deliverable --project prj-0001 --changed-only --run-id deliverable-check
671
779
  specdojo grade plan --target kata --changed-only --project prj-0001
672
780
  # 評価対象・参考資料・比較リファレンスを plan へ埋め込む
673
781
  specdojo grade plan --target kata --changed-only --embed-documents --project prj-0001
@@ -684,6 +792,14 @@ specdojo grade apply --target kata --path <document.md> \
684
792
  specdojo grade validate --target kata --project prj-0001
685
793
  ```
686
794
 
795
+ `grade run` の `--run-id` は必須です。選択文書と完了状況を `execution_path/grade/generated/runs/<run-id>/run.json` へ保存し、同じ引数での再実行では完了済み文書を再適用しません。選択は初回に固定するため、`--changed-only` で実行中に文書が選択から外れても再開できます。対象内容、観点、完了条件、突き合わせ先、引数が変わった場合や保存済み結果が置き換わった場合は、新しい run ID を使います。`--work-dir` で保存先を変更できます。`--limit` は初回の選択件数を制限します。
796
+
797
+ `--by`(別名 `--stage-1-executor`)を省略すると、名簿の有効な review executor を既存の priority 規則で選びます。該当しなければ旧形式の review agent を選びます。別名で指定してもサイドカーの `graded_by` と run 記録には実体名を残します。`--exec-defaults` で起動設定を引き継げます。`--dry-run` は選択と actor を表示し、agent の起動とファイル更新を行いません。同一 project の grade 実行は排他制御します。
798
+
799
+ ネイティブ経路は `--stages 1` と機械 reporter を扱います。`--reference` と `--embed-documents` は plan に反映し、`--kind` は kata の `rulebook` / `recipe` / `sample` / `template` / `all`(既定)を選びます。失敗した文書と理由は run 記録に残し、終了コード 1 を返します。`--max-stage-failures`(既定 3)に達するまでは未完了段を再開できます。日本語 finding の表示用翻訳は `translation-plan` / `localize` で別途行います。開発用シェルの実験的な 3 段構成は CLI の対象外です。
800
+
801
+ 宣言済み `project.repos` 配下の Markdown は、プロジェクトリポジトリから `../product/docs/document.md` のように指定できます。宣言外のリポジトリや symlink による範囲外への参照は拒否します。
802
+
687
803
  `--target` は `kata` または `deliverable` です。`--path` は繰り返し指定でき、明示した Markdown 文書だけを対象にします。ただし、パス要素に `generated` を含む生成文書と `trash` を含む退避済み文書は自動探索から除外し、`--path` で明示した場合も入力エラーとして拒否します。`--changed-only` は grade result サイドカーの `content_hash` と現在の成果物ファイル全体の SHA-256 を比較します。`grade apply` はサイドカーだけを更新するため、評価結果の書き込み自体で成果物が変更扱いになることはありません。
688
804
 
689
805
  `--changed-only` は、対象文書の本文が変わった文書に加えて、突き合わせ先が変わった文書も選びます。突き合わせ先は、対象文書に適用される継続評価の観点が `comparison_sources` で宣言したものです。`grade apply` は評価時点の突き合わせ先の SHA-256 をサイドカーの `source_hashes` へ記録し、`--changed-only` は記録と現在の値が 1 つでも異なる文書を選びます。宣言できる突き合わせ先と、`source_hashes` のキーは次のとおりです。
@@ -737,7 +853,7 @@ finding の忠実性照合では、message に限り、Unicode の正準等価
737
853
 
738
854
  移行期間中は `--analysis-from` を省略し `--from` だけを指定する従来の1段構成も受理します。既存の保存済み plan や GradeSubmission を適用するための互換経路であり、新しく生成した plan では `--analysis-from` を指定します。旧 GradeSubmission の `graded_by` も入力互換性のため受理しますが、記録には使いません。
739
855
 
740
- 複数対象は、生成された executor plan を順に処理し、executor 応答を保存して直ちに `grade apply --path <document> --analysis-from <executor-output>` で反映します。agent 起動は `agent run`、応答の保存と受け渡しは呼び出し側が担い、`grade` は plan の生成と結果の検証・反映に限定されます。この単位で処理すると、後続文書が失敗しても適用済みの grade は保持されます。保存済み executor plan は `exec trial` などで同じ入力を複数 agent へ渡す用途にも利用できます。
856
+ 複数対象は、生成された executor plan を順に処理し、executor 応答を保存して直ちに `grade apply --path <document> --analysis-from <executor-output>` 相当の処理で反映します。`grade run` がこの連携を担い、後続文書が失敗しても適用済みの grade を保持します。部品ごとに実行する場合は、`agent run` で起動した応答の保存と受け渡しを呼び出し側が担います。保存済み executor plan は `exec trial` などで同じ入力を複数 agent へ渡す用途にも利用できます。
741
857
 
742
858
  ### 8.1. npm package で 1 文書を評価する
743
859
 
@@ -1032,7 +1148,7 @@ npx specdojo devcontainer scaffold --workspace-name app1-workspace
1032
1148
 
1033
1149
  `.devcontainer/` が既に存在する場合は何も書き込まず、置き換える場合だけ `--force` を指定します。上書き前や初回生成前は `--dry-run` で対象ファイルを確認してください。生成設定は provider の設定ディレクトリを名前付きボリュームへ保存してコンテナ再作成後も利用できるようにし、ホストの認証情報・秘密鍵・`.env` を直接マウントしません。認証は生成したコンテナ内で利用者が必要なときに行い、自動ログインはしません。
1034
1150
 
1035
- 生成する `devcontainer.json` は `${localWorkspaceFolder}/..` を、ホスト側の親ディレクトリ名に合わせた `/workspaces/<親名>` へマウントし、`workspaceFolder` をその中の `${localWorkspaceFolderBasename}` へ向けます。例えば `app1-workspace/app1-specdojo` で scaffold すると、作業ディレクトリは `/workspaces/app1-workspace/app1-specdojo` です。別リポジトリ構成の `repos` と `worktree_base` はプロジェクトリポジトリの外にあるため、親ディレクトリを共有することでプロダクトリポジトリと exec の worktree をコンテナから利用できます。`post-create.sh` はマウントした親ディレクトリ配下の Git リポジトリと worktree を `safe.directory` の対象にします。親ディレクトリ内のその他のファイルもコンテナから見えるため、コンテナへ公開しないファイルは同じ親ディレクトリに置かないでください。
1151
+ 生成する `devcontainer.json` は `${localWorkspaceFolder}/..` を、ホスト側の親ディレクトリ名に合わせた `/workspaces/<親名>` へマウントし、`workspaceFolder` をその中の `${localWorkspaceFolderBasename}` へ向けます。例えば `app1-workspace/app1-specdojo` で scaffold すると、作業ディレクトリは `/workspaces/app1-workspace/app1-specdojo` です。別リポジトリ構成の `repos` と `worktree_base` はプロジェクトリポジトリの外にあるため、親ディレクトリを共有することでプロダクトリポジトリと exec の worktree をコンテナから利用できます。`post-create.sh` はマウントした親ディレクトリ配下の Git リポジトリと worktree を `safe.directory` の対象にします。親ディレクトリ内のその他のファイルもコンテナから見えるため、コンテナへ公開しないファイルは同じ親ディレクトリに置かないでください。また、`shutdownAction: "none"` を指定してエディタ切断時もコンテナを即時停止させず、バックグラウンド処理や tmux セッションを維持できるようにします。
1036
1152
 
1037
1153
  親名には英数字・`.`・`_`・`-` だけを使用できます。空白、`/`、制御文字などを含む場合は、意図しないパスへ置換せずエラーにします。必要なら `--workspace-name <name>` で有効な名前を指定してください。`specdojo init --devcontainer` でも同じオプションを指定できます。コンテナ内で作った Git worktree は作成時の絶対パスを記録するため、ホスト側の親ディレクトリ名を変えて `.devcontainer/` を作り直す場合は、`--workspace-name` に以前の名前を指定してコンテナ内のパスを保ってください。
1038
1154
 
@@ -87,6 +87,8 @@ SpecDojo Configuration Reference
87
87
 
88
88
  別名は `[a-z0-9-]+` とし、ローカルの `projects` の ID と重ねられません。`path` は存在するディレクトリでなければならず、絶対パスは使えません。起票時は相手の `node_modules/.bin/specdojo` を使うため、相手に SpecDojo 0.4.2 以上が必要です。`orchestrator launch` は `repos` に加えて、宣言したすべての外部リポジトリにも provider 別の編集許可を付けます。
89
89
 
90
+ 相手に `node_modules/.bin/specdojo` がなく、相手の `package.json` の `name` が `specdojo` の場合は、呼び出し元と同じ Node.js で `node <相手>/dist/specdojo.js` を起動します。SpecDojo 自身のリポジトリを指定する場合は、相手で `npm install` と `npm run build` を実行してください。`dist/specdojo.js` がなければ `npm run build` を案内して停止します。CLI の版はこの起動方法でも 0.4.2 以上が必要です。
91
+
90
92
  ## 3. projectのパスキー
91
93
 
92
94
  `projects.<project-id>` に指定するキーです。`base_path` 以外の表中のパスは、`base_path` があればそこからの相対パス、無ければリポジトリルートからの相対パスとして解決します。
@@ -122,13 +124,14 @@ project の `integration_branch` は、`repos[].integration_branch` とは別の
122
124
 
123
125
  `projects.<project-id>.run` に指定します。これらのパスは `base_path` の影響を受けず、リポジトリルート基準です。
124
126
 
125
- | キー | 既定値 | 役割・利用箇所 |
126
- | ------------------------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
127
- | `exec_defaults` | なし | provider、権限、リトライなどを定義する exec defaults ファイルです。agent を起動する `exec run` が参照します。 |
128
- | `agent_config` | なし | `exec_defaults` の旧キーです。互換目的でのみ利用し、新しい設定では `exec_defaults` を使います。 |
129
- | `parent_validations` | `[]` | この project だけで追加する親 runner の検証です。`exec_defaults` の `pipeline.parent_validations` の後ろへ指定順に加えます。 |
130
- | `worktree_base` | `../worktrees` | `exec run --worktree` / `--auto` と `exec trial` が作る worktree の親です。リポジトリ外を指定します。 |
131
- | `register_date_timezone` | `UTC` | 登録簿の「登録日」「完了日」を日時から暦日へ変換する IANA タイムゾーン名です。例は `Asia/Tokyo` です。 |
127
+ | キー | 既定値 | 役割・利用箇所 |
128
+ | ---------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
129
+ | `exec_defaults` | なし | provider、権限、リトライなどを定義する exec defaults ファイルです。agent を起動する `exec run` が参照します。 |
130
+ | `agent_config` | なし | `exec_defaults` の旧キーです。互換目的でのみ利用し、新しい設定では `exec_defaults` を使います。 |
131
+ | `parent_validations` | `[]` | この project だけで追加する親 runner の検証です。`exec_defaults` の `pipeline.parent_validations` の後ろへ指定順に加えます。 |
132
+ | `parent_validations_exclude` | `[]` | 共有の `pipeline.parent_validations` から除外する ID と実行先の組です。除外後に `parent_validations` を追記します。 |
133
+ | `worktree_base` | `../worktrees` | `exec run --worktree` / `--auto` と `exec trial` が作る worktree の親です。リポジトリ外を指定します。 |
134
+ | `register_date_timezone` | `UTC` | 登録簿の「登録日」「完了日」を日時から暦日へ変換する IANA タイムゾーン名です。例は `Asia/Tokyo` です。 |
132
135
 
133
136
  `parent_validations` の要素は、共有 defaults と同じく検証 ID、または `{ "id": "<id>", "repo": "<repo>" }` です。共有 defaults を複製せず、プロダクトリポジトリを持つ project だけに検証を追加できます。たとえば `prj-0002` だけで `specdojo-lp` の型と lint を検査する設定は次のとおりです。
134
137
 
@@ -149,7 +152,27 @@ project の `integration_branch` は、`repos[].integration_branch` とは別の
149
152
  }
150
153
  ```
151
154
 
152
- 有効な一覧は「共有 defaults の `pipeline.parent_validations` → project の `run.parent_validations`」の順です。同じ ID と実行先の組が両方にある場合は重複として agent 起動前にエラーになります。`run.parent_validations` を省略した project には共有 defaults だけが適用されるため、`repos` を持たない別 project はプロダクトリポジトリ向けの追加検証に影響されません。許可される ID と実行結果の記録は [[specdojo:exec-config-guide|exec設定ガイド]] を参照してください。
155
+ 除外を指定しない場合、有効な一覧は「共有 defaults の `pipeline.parent_validations` → project の `run.parent_validations`」の順です。同じ ID と実行先の組が両方にある場合は重複として agent 起動前にエラーになります。追加も除外も省略した project には共有 defaults だけが適用されるため、`repos` を持たない別 project はプロダクトリポジトリ向けの追加検証に影響されません。許可される ID と実行結果の記録は [[specdojo:exec-config-guide|exec設定ガイド]] を参照してください。
156
+
157
+ 共有検証を減らす場合は `run.parent_validations_exclude` を指定します。要素の形式は `parent_validations` と同じです。有効な一覧は「共有の `pipeline.parent_validations` から除外 → `run.parent_validations` を追記」の順になり、共有一覧の残りと追記分の順序を保ちます。除外を省略するか `[]` にした project は従来どおりです。共有 defaults のほかの設定や、別 project の検証は変わりません。
158
+
159
+ たとえば共有一覧が `lint-fm`・`lint-md`・`lint-ts`・`typecheck`・`test-unit`・`test-integration`・`validate-schema` の場合、`prj-0002` の `run` を次のようにすると、`lint-fm`・`lint-md` と `specdojo-lp` の `typecheck` だけが有効になります。`repos` は上の例と同じ宣言を使います。
160
+
161
+ ```json
162
+ {
163
+ "exec_defaults": ".specdojo/exec-defaults.yaml",
164
+ "parent_validations_exclude": [
165
+ "lint-ts",
166
+ "typecheck",
167
+ "test-unit",
168
+ "test-integration",
169
+ "validate-schema"
170
+ ],
171
+ "parent_validations": [{ "id": "typecheck", "repo": "specdojo-lp" }]
172
+ }
173
+ ```
174
+
175
+ 除外の ID だけの指定は `{ "id": "<id>", "repo": "project" }` と同じで、同じ ID の別リポジトリ向け検証には一致しません。未知の ID、不正な要素、共有一覧に存在しない ID と実行先の組の除外、除外一覧内または最終一覧内の組の重複は agent 起動前に設定エラーになります。除外前の共有一覧自体も検証します。除外は project の追加分には適用せず、除外した組を `parent_validations` で末尾に戻すことはできます。共有 defaults に新しく追加された検証は、除外に指定しない限り継承します。
153
176
 
154
177
  `config init` は一般既定の `../worktrees` ではなく、実行したリポジトリのディレクトリ名から作る `../<リポジトリ名>-worktrees` を `worktree_base` へ明示します。例えば `app1-specdojo/` で実行した場合は `../app1-specdojo-worktrees` です。
155
178
 
@@ -55,26 +55,28 @@ Project Register Documentation Rules
55
55
 
56
56
  個票には `register-item-frontmatter.schema.yaml` が定義する次の項目を置く。未定の担当、期限、完了日時、結論は表用のプレースホルダを保存せず、該当キーを省略する(期限なしだけは `due_on: null`)。
57
57
 
58
- | 項目 | 説明 | 必須 |
59
- | --------------- | -------------------------------------------- | ---- |
60
- | `id` | `<project-id>:pjr-XXXX-<topic>` | ○ |
61
- | `type` | `project` | ○ |
62
- | `status` | 文書成熟度。`draft` / `ready` / `deprecated` | ○ |
63
- | `rulebook` | `specdojo:pjr-rulebook` | ○ |
64
- | `part_of` | `<project-id>:pjr-index` を要素に持つ配列 | ○ |
65
- | `item_type` | 登録項目の分類 | ○ |
66
- | `item_status` | 登録項目の処理状態 | ○ |
67
- | `priority` | 対応優先度 | ○ |
68
- | `difficulty` | agent 振り分け用の作業難易度 | 任意 |
69
- | `owner` | 主担当者または役割 | 任意 |
70
- | `registered_at` | 起票日時 | 任意 |
71
- | `due_on` | 対応期限または判断期限 | 任意 |
72
- | `completed_at` | 完了・却下・決定日時 | 条件 |
73
- | `block_reason` | `waiting` へ遷移した直近の理由 | 任意 |
74
- | `conclusion` | 終端時の結論要約 | 任意 |
75
- | `derived_from` | 起票の元になった登録項目 ID の配列 | 任意 |
76
- | `approach` | 対象を作成・修正するときの進め方 | 任意 |
77
- | `targets` | 変更対象文書の doc id リスト | 任意 |
58
+ | 項目 | 説明 | 必須 |
59
+ | ----------------- | ------------------------------------------------ | ---- |
60
+ | `id` | `<project-id>:pjr-XXXX-<topic>` | ○ |
61
+ | `type` | `project` | ○ |
62
+ | `status` | 文書成熟度。`draft` / `ready` / `deprecated` | ○ |
63
+ | `rulebook` | `specdojo:pjr-rulebook` | ○ |
64
+ | `part_of` | `<project-id>:pjr-index` を要素に持つ配列 | ○ |
65
+ | `item_type` | 登録項目の分類 | ○ |
66
+ | `item_status` | 登録項目の処理状態 | ○ |
67
+ | `priority` | 対応優先度 | ○ |
68
+ | `difficulty` | agent 振り分け用の作業難易度 | 任意 |
69
+ | `owner` | 主担当者または役割 | 任意 |
70
+ | `registered_at` | 起票日時 | 任意 |
71
+ | `due_on` | 対応期限または判断期限 | 任意 |
72
+ | `completed_at` | 完了・却下・決定日時 | 条件 |
73
+ | `block_reason` | `waiting` へ遷移した直近の理由 | 任意 |
74
+ | `conclusion` | 終端時の結論要約 | 任意 |
75
+ | `derived_from` | 起票の元になった登録項目 ID の配列 | 任意 |
76
+ | `approach` | 対象を作成・修正するときの進め方 | 任意 |
77
+ | `target_path` | カタログなしで作成する成果物のリポジトリ相対パス | 任意 |
78
+ | `target_rulebook` | 対象成果物の rulebook ID | 任意 |
79
+ | `targets` | 変更対象文書の doc id リスト | 任意 |
78
80
 
79
81
  - `status` は文書成熟度、`item_status` は処理状態であり、同じ状態軸として扱わない。
80
82
  - `item_type`、`item_status`、`priority`、`difficulty` の値は schema の enum だけを使用する。`difficulty` は `hard` / `medium` / `easy` のいずれかとし、省略時は従来の agent 自動選択を使う。
@@ -138,12 +140,16 @@ Project Register Documentation Rules
138
140
  - 関連ドキュメントには、判断根拠、変更対象、影響先、追跡先のうち該当する文書を記載する。
139
141
  - 実行中に問題や後続作業を見つけて別の登録項目を起票するときは、起票元を `derived_from` に必ず記録する。decision から todo を起票する場合も同じ関係を使い、decision 本文へ追跡先を重複記載しない。既存本文の追跡先は移行のために書き換えない。
140
142
  - 本項目の実施において確実に変更する対象文書が分かっている場合は、その文書 ID を Frontmatter の `targets` 配列へ宣言する。宣言した `targets` は agent 実行時の変更網羅検証(target coverage)に用いられる。未知の場合や対象を固定しない場合は宣言を省略する。
141
- - `approach` を宣言する場合、`targets` は 1 件だけ必須とする。`fully-guided`・`recipe-guided`・`freeform`・`bootstrap`・`retrofit`・`cross-deliverable-dedup`・`finalize`・`bootstrap-finalize` の対象は成果物カタログにある成果物の doc id とし、まだ文書がない成果物もカタログで解決する。`rulebook-maintenance`・`recipe-maintenance`・`sample-maintenance`・`template-maintenance` の対象は、名前に対応する種別の kata の doc id とし、文書索引で解決する。対応する正本で解決できない ID や、`approach` と種別が合わない対象は使用しない。
143
+ - `approach` を宣言する場合、`targets` は 1 件だけ必須とする。成果物の対象はカタログを優先して解決する。`cross-deliverable-dedup` はカタログを必須とする。それ以外の成果物の approach(`fully-guided`・`recipe-guided`・`freeform`・`bootstrap`・`retrofit`・`finalize`・`bootstrap-finalize`)は、カタログなしでも既存文書の索引と `specdojo.rulebook`、または個票の `target_path` と `target_rulebook` から解決できる。新規文書は両フィールドを必須とし、リポジトリ外のパスや別文書との衝突、既存文書と指定の不一致は認めない。カタログ設定済みで対象が未登録の場合も両フィールドがある場合だけ同じ解決を使う。`rulebook-maintenance`・`recipe-maintenance`・`sample-maintenance`・`template-maintenance` の対象は、名前に対応する種別の kata の doc id とし、文書索引で解決する。対応する正本で解決できない ID や、`approach` と種別が合わない対象は使用しない。
144
+
145
+ - カタログなしの完了基準は個票の完了条件と rulebook とする。recipe・sample・template は rulebook frontmatter から辿り、`not-needed` のものを対象に含めない。`fully-guided` の必要な一式、`recipe-guided` の recipe が不足する場合は起票・更新を拒否する。
146
+ - カタログなしの `bootstrap` は `target_path`、新しい `target_rulebook`、設定の `kata_authority` を必須とする。既存 rulebook を再利用しない。rulebook の名前部分から recipe・sample・template の ID を導出し、`docs/ja/specdojo/<kind>s/<kata_authority>/` に配置する候補を plan へ示す。成果物には新しい `specdojo.rulebook` を記録する。
147
+ - `finalize`・`bootstrap-finalize` は既存成果物だけを対象にし、カタログなしでは個票の完了条件を確認チェック表にする。後者は成果物と frontmatter から辿る kata 一式を確定対象とする。
142
148
 
143
149
  ### 5.2. 構造化フィールドと生成
144
150
 
145
151
  - 新しい項目は `register add` で作成し、個票の Frontmatter に初期値を書き込む。全 type で個票を省略しない。
146
- - 担当・期限・結論・topic・`derived_from`・`approach`・`targets` などを変更するときは `register update`、処理状態を変えるときは状態遷移コマンドを使用する。`register add` と `register update` では、起票元に繰り返し指定できる `--from`、進め方に `--approach`、対象に繰り返し指定できる `--target` を使う。起票元、`approach`、対象を削除するときは、それぞれ `--from -`、`--approach -`、`--target -` を指定する。待機理由は `register wait --reason` で記録し、誤った現在値を手動補正するときは `register update --block-reason -` で削除する。
152
+ - 担当・期限・結論・topic・`derived_from`・`approach`・`targets` などを変更するときは `register update`、処理状態を変えるときは状態遷移コマンドを使用する。`register add` と `register update` では、起票元に繰り返し指定できる `--from`、進め方に `--approach`、対象に繰り返し指定できる `--target`、成果物の配置と rulebook に `--target-path` と `--target-rulebook` を使う。配置と rulebook の明示指定もそれぞれ `-` で削除できる。起票元、`approach`、対象を削除するときは、それぞれ `--from -`、`--approach -`、`--target -` を指定する。待機理由は `register wait --reason` で記録し、誤った現在値を手動補正するときは `register update --block-reason -` で削除する。
147
153
  - `register build` は個票を読み取り、一覧・派生ビューを再生成する。`generated/pjr-derived-items.md` では `derived_from` を逆引きし、元の項目から派生先を辿れるようにする。一覧を編集して個票へ反映する経路はない。
148
154
  - `register add`、状態遷移、`register update`、`register renumber` は現在値を個票へ、イベントを対応する項目別ログへ記録する。`--by` で actor、`--reason` で理由を明示でき、省略時は予約 actor の `SpecDojo` を記録する。
149
155
  - `--by` に指定できるのは、project の `pm-members.yaml` にある人の nickname、repository の `.specdojo/agent-members.yaml` にある agent の nickname または alias、予約 actor の `SpecDojo`・`specdojo-orchestrator`・`night-orchestrator` に限る。agent の alias は実体の nickname に解決して記録し、名簿にも予約一覧にもない値は書き込み前に拒否する。
@@ -207,9 +207,25 @@ properties:
207
207
  final_message:
208
208
  type: string
209
209
  maxLength: 4000
210
+ completion_status:
211
+ description: >
212
+ Executor-reported task completion, independent of process status. Omitted legacy reports
213
+ imply complete. Incomplete tasks must not proceed to integration.
214
+ type: string
215
+ enum: [complete, incomplete]
216
+ handoff:
217
+ description: >
218
+ Redacted, bounded executor notes preserved mechanically in the edit result handoff after
219
+ the reporter stage. Optional for compatibility with existing reports and evidence.
220
+ type: array
221
+ maxItems: 100
222
+ items:
223
+ type: string
224
+ minLength: 1
225
+ maxLength: 4000
210
226
  block_reason:
211
227
  description: >
212
- Runner-derived failure or protection reason. Reporter prose never supplies this field.
228
+ Runner-derived failure, protection, or incomplete-work reason. Reporter prose never supplies this field.
213
229
  type: string
214
230
  minLength: 1
215
231
  maxLength: 1000
@@ -31,7 +31,7 @@ properties:
31
31
  enum: [kata, deliverable]
32
32
  document:
33
33
  type: string
34
- pattern: "^docs/.+\\.md$"
34
+ pattern: "^(?!/).+\\.md$"
35
35
  content_hash:
36
36
  type: string
37
37
  pattern: "^[a-f0-9]{64}$"
@@ -59,6 +59,8 @@ $defs:
59
59
  - approach
60
60
  - targets
61
61
  - sources
62
+ - target_path
63
+ - target_rulebook
62
64
  - derived_from
63
65
  - autopilot
64
66
  from: