specdojo 0.2.0 → 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.
Files changed (170) hide show
  1. package/.github/agents/specdojo-orchestrator.md +165 -0
  2. package/CHANGELOG.md +280 -0
  3. package/README.md +143 -30
  4. package/dist/agent-response.js +20 -0
  5. package/dist/agent.js +4 -4
  6. package/dist/build-command.js +28 -8
  7. package/dist/dashboard.js +140 -9
  8. package/dist/devcontainer-command.js +43 -0
  9. package/dist/devcontainer-scaffold.js +165 -0
  10. package/dist/exec-agent-config.js +107 -9
  11. package/dist/exec-agent-git-state.js +18 -0
  12. package/dist/exec-agent-protected-config.js +46 -8
  13. package/dist/exec-evidence.js +254 -11
  14. package/dist/exec-format.js +13 -4
  15. package/dist/exec-handoff.js +336 -0
  16. package/dist/exec-parent-validation.js +317 -43
  17. package/dist/exec-pipeline-state.js +74 -9
  18. package/dist/exec-plans.js +115 -113
  19. package/dist/exec-protection-handoff.js +43 -2
  20. package/dist/exec-provider-scaffold.js +247 -15
  21. package/dist/exec-register-resume.js +65 -19
  22. package/dist/exec-register.js +9 -3
  23. package/dist/exec-repo-integration.js +811 -0
  24. package/dist/exec-repo-trace.js +182 -0
  25. package/dist/exec-reporter.js +613 -132
  26. package/dist/exec-results.js +81 -56
  27. package/dist/exec-run-lock.js +110 -107
  28. package/dist/exec-run.js +1585 -356
  29. package/dist/exec-shared.js +7 -0
  30. package/dist/exec-slot-lock.js +242 -0
  31. package/dist/exec-task-repos.js +415 -0
  32. package/dist/exec-trial.js +51 -25
  33. package/dist/exec-worktree-command.js +87 -43
  34. package/dist/exec-worktree-ops.js +502 -57
  35. package/dist/exec-worktree.js +114 -27
  36. package/dist/exec.js +13 -6
  37. package/dist/grade-result.js +128 -0
  38. package/dist/grade.js +809 -72
  39. package/dist/init-command.js +443 -0
  40. package/dist/job.js +160 -10
  41. package/dist/orchestrator.js +213 -0
  42. package/dist/package-paths.js +19 -1
  43. package/dist/register-event-merge.js +169 -0
  44. package/dist/register-item.js +7 -1
  45. package/dist/register.js +294 -86
  46. package/dist/review-grade.js +252 -0
  47. package/dist/review-plan.js +111 -1
  48. package/dist/review-types.js +40 -1
  49. package/dist/routine.js +72 -5
  50. package/dist/schedule-build.js +2 -2
  51. package/dist/schedule.js +17 -4
  52. package/dist/specdojo-config.js +466 -20
  53. package/dist/specdojo-gitignore.js +135 -0
  54. package/dist/specdojo.js +8 -1
  55. package/dist/viewpoint-document-kinds-check.js +128 -0
  56. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +348 -90
  57. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +51 -17
  58. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +7 -5
  59. package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +29 -31
  60. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +34 -55
  61. package/docs/ja/specdojo/exec-templates/xrp-job-template.md +54 -0
  62. package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +28 -37
  63. package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +29 -34
  64. package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +30 -30
  65. package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +29 -34
  66. package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +29 -34
  67. package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +29 -34
  68. package/docs/ja/specdojo/exec-templates/xrp-template.md +29 -28
  69. package/docs/ja/specdojo/exec-templates/xrr-template.md +11 -9
  70. package/docs/ja/specdojo/guides/docs-editing-guide.md +20 -0
  71. package/docs/ja/specdojo/guides/docs-structure-guide.md +103 -70
  72. package/docs/ja/specdojo/guides/exec-config-guide.md +91 -47
  73. package/docs/ja/specdojo/guides/exec-operation-guide.md +124 -27
  74. package/docs/ja/specdojo/guides/exec-worktree-guide.md +40 -11
  75. package/docs/ja/specdojo/guides/kata-guide.md +4 -4
  76. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +25 -4
  77. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +1 -1
  78. package/docs/ja/specdojo/guides/practice-system-composition-guide.md +13 -13
  79. package/docs/ja/specdojo/guides/quick-start-guide.md +261 -32
  80. package/docs/ja/specdojo/guides/register-operation-guide.md +31 -14
  81. package/docs/ja/specdojo/guides/release-v0-3-0-migration-guide.md +264 -0
  82. package/docs/ja/specdojo/guides/remote-host-development-guide.md +184 -0
  83. package/docs/ja/specdojo/guides/review-guide.md +195 -158
  84. package/docs/ja/specdojo/guides/routine-operation-guide.md +74 -9
  85. package/docs/ja/specdojo/guides/ryu-guide.md +32 -30
  86. package/docs/ja/specdojo/guides/schedule-design-guide.md +10 -10
  87. package/docs/ja/specdojo/guides/schedule-operation-guide.md +1 -1
  88. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +58 -33
  89. package/docs/ja/specdojo/guides/use-case-guide.md +3 -3
  90. package/docs/ja/specdojo/guides/waza-guide.md +15 -2
  91. package/docs/ja/specdojo/index.md +2 -2
  92. package/docs/ja/specdojo/philosophy/specdojo-philosophy.md +5 -5
  93. package/docs/ja/specdojo/recipes/bps-recipe.md +213 -0
  94. package/docs/ja/specdojo/recipes/pm-members-recipe.md +52 -117
  95. package/docs/ja/specdojo/references/command-reference.md +336 -93
  96. package/docs/ja/specdojo/references/deliverables-reference.md +1 -1
  97. package/docs/ja/specdojo/references/directory-layout-reference.md +13 -9
  98. package/docs/ja/specdojo/references/specdojo-config-reference.md +107 -24
  99. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +132 -220
  100. package/docs/ja/specdojo/rulebooks/br-rulebook.md +6 -44
  101. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +2 -0
  102. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +0 -87
  103. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +61 -39
  104. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +0 -87
  105. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +1 -33
  106. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +0 -137
  107. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +0 -247
  108. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +0 -83
  109. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +4 -2
  110. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +78 -150
  111. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +5 -4
  112. package/docs/ja/specdojo/rulebooks/sch-rulebook.md +1 -1
  113. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +0 -11
  114. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +0 -61
  115. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +2 -47
  116. package/docs/ja/specdojo/samples/bps-sample.md +74 -21
  117. package/docs/ja/specdojo/samples/gl-sample.yaml +17 -1
  118. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +28 -0
  119. package/docs/ja/specdojo/samples/pm-members-sample.yaml +2 -67
  120. package/docs/ja/specdojo/samples/pm-organization-sample.md +8 -7
  121. package/docs/ja/specdojo/samples/pm-raci-sample.md +1 -1
  122. package/docs/ja/specdojo/samples/tml-sample.yaml +40 -0
  123. package/docs/ja/specdojo/standards/document-metadata-standard.md +21 -16
  124. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +14 -14
  125. package/docs/ja/specdojo/standards/job-definition-standard.md +37 -17
  126. package/docs/ja/specdojo/standards/people-and-organization-definition-standard.md +37 -32
  127. package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +1 -1
  128. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +21 -11
  129. package/docs/ja/specdojo/templates/agent-members-template.yaml +25 -0
  130. package/docs/ja/specdojo/templates/bps-template.md +91 -0
  131. package/docs/ja/specdojo/templates/pm-members-template.yaml +2 -59
  132. package/docs/specdojo/schemas/v1/agent-members.schema.yaml +76 -0
  133. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +4 -2
  134. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +55 -2
  135. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +93 -6
  136. package/docs/specdojo/schemas/v1/exec-reporter-output.schema.yaml +27 -78
  137. package/docs/specdojo/schemas/v1/gl.schema.yaml +87 -0
  138. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +33 -0
  139. package/docs/specdojo/schemas/v1/job-run.schema.yaml +27 -0
  140. package/docs/specdojo/schemas/v1/job.schema.yaml +25 -0
  141. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +49 -1
  142. package/docs/specdojo/schemas/v1/pm-members.schema.yaml +9 -169
  143. package/docs/specdojo/schemas/v1/pm-review-viewpoints.schema.yaml +100 -10
  144. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +13 -0
  145. package/docs/specdojo/schemas/v1/routine-run.schema.yaml +3 -0
  146. package/docs/specdojo/schemas/v1/routine.schema.yaml +7 -0
  147. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +110 -0
  148. package/package.json +16 -9
  149. package/templates/antigravity/README.md +60 -0
  150. package/templates/antigravity/agent-members-snippet.yaml +61 -0
  151. package/templates/antigravity/exec-defaults-snippet.yaml +39 -0
  152. package/templates/antigravity/orchestrator.md +157 -0
  153. package/templates/antigravity/settings.global.json +55 -0
  154. package/templates/claude/agents/claude-executor.md +14 -0
  155. package/templates/claude/agents/claude-reporter.md +16 -0
  156. package/templates/claude/agents/specdojo-orchestrator.md +164 -0
  157. package/templates/claude/settings.edit.json +27 -1
  158. package/templates/codex/README.md +5 -4
  159. package/templates/codex/agents/specdojo-orchestrator.toml +165 -0
  160. package/templates/codex/orchestrator.md +157 -0
  161. package/templates/copilot/README.md +7 -5
  162. package/templates/copilot/{pm-members-snippet.yaml → agent-members-snippet.yaml} +4 -2
  163. package/templates/devcontainer/devcontainer.json +27 -0
  164. package/templates/devcontainer/emacs/init.el +88 -0
  165. package/templates/devcontainer/post-create.sh +62 -0
  166. package/templates/init-agent-members.yaml +200 -0
  167. package/templates/init-exec-defaults.yaml +72 -0
  168. package/templates/opencode/agents/specdojo-orchestrator.md +204 -0
  169. package/docs/ja/specdojo/exec-templates/xrp-viewpoint-detail-template.md +0 -7
  170. package/docs/ja/specdojo/exec-templates/xrr-viewpoint-detail-template.md +0 -7
@@ -1,38 +1,91 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:bps-sample
4
- type: project
4
+ type: flow
5
5
  status: draft
6
6
  rulebook: specdojo:bps-rulebook
7
7
  ---
8
8
 
9
- # [業務プロセス仕様](../rulebooks/bps-rulebook.md) サンプル
9
+ # 補充依頼確定
10
10
 
11
- ## 1. 目的と適用範囲
11
+ 在庫が補充基準を下回ったことを受け、店主代表が補充対象と依頼数量を判断し、仕入グループへ渡す補充依頼を確定する。
12
12
 
13
- 本書は、業務プロセスの処理内容を定義するための最小サンプルである。
13
+ ## 1. 概要
14
14
 
15
- ## 2. 入力情報
15
+ - 業務目的: 人気商品の欠品を減らすため、現在庫と商品ごとの補充基準から仕入れが必要な商品と依頼数量を確定する。
16
+ - プロセス領域: 在庫グループの補充判断(`P-06`)
17
+ - 対象者: 店主代表は補充判断を承認し、開発担当と同行レビュー担当は判断条件と業務成果を後続設計・レビューに利用する。
18
+ - 主担当: 店主代表
19
+ - 開始点: 販売または入荷を反映した現在庫が確定し、補充基準割れを検出した時点
20
+ - 終了点: 補充依頼が仕入グループへ引き渡され、参照可能になった時点、または補充不要が記録された時点
21
+ - 対象外: 仕入先の決定、発注内容の承認・送付、入荷検品、売場補充
16
22
 
17
- - 対象: 駄菓子屋の販売管理システム
18
- - 前提: プロジェクト文脈は handbook の共通方針に準拠する
19
- - 参照: `../rulebooks/bps-rulebook.md`
23
+ 本書は単一店舗の日常的な補充判断を扱う。発注から入荷、売場補充までのグループ横断順序は `cdfd-uc-replenishment`、仕入グループ内の処理は `cdfd-purchasing` を正本とする。
20
24
 
21
- ## 3. 記述内容
25
+ ## 2. トリガー
22
26
 
23
- - 主な内容: 業務プロセス概要、トリガー、前提、入力、処理、出力 など
24
- - 必須観点: 対象、条件、判定基準、責任者
27
+ | トリガー ID | 出来事 | 発生元 | 受領情報 | 開始条件 | 不成立時の扱い |
28
+ | ----------- | -------------------------- | ---------------- | -------------------------------- | ------------------------------------------------------ | -------------- |
29
+ | `T-01` | 現在庫が補充基準を下回った | 在庫確認プロセス | 商品、現在庫、補充基準、確認時刻 | 在庫確認プロセスから対象商品と現在庫が引き渡されている | 起動しない |
25
30
 
26
- ## 4. 最小記述例
31
+ トリガーは在庫確認プロセスの判定結果であり、在庫記録の物理的な更新方式には依存しない。
27
32
 
28
- | 項目 | 値 | 備考 |
29
- | ------------ | ------------------------------------------------------- | ------------------------------------ |
30
- | ドキュメント | [業務プロセス仕様](../rulebooks/bps-rulebook.md) | 最小サンプル |
31
- | 目的 | 業務プロセスの処理内容を定義する | specdojo:deliverables-reference 準拠 |
32
- | 主な内容 | 業務プロセス概要、トリガー、前提、入力、処理、出力 など | 要点のみ記載 |
33
+ ## 3. 前提条件
33
34
 
34
- ## 5. 未解決事項
35
+ - 店主代表が補充要否と依頼数量を最終判断できる。家族利用者代表が検出した場合も、補充依頼の確定は店主代表が行う。
36
+ - 数量に関する用語の関係は以下の通りとする。
37
+ - 補充基準: 補充が必要か判定するための閾値。現在庫がこれを下回ると補充要となる。
38
+ - 補充必要数: `br-reorder-point` が判定する、補充に必要な数量。算出方法は `br-reorder-point` を正本とする。
39
+ - 依頼数量: 補充必要数を発注単位に合わせて調整し、仕入グループへ依頼する最終的な数量。
40
+ - 発注単位: 仕入先が指定する、発注可能な最小の数量単位。
35
41
 
36
- | 論点 | 処理方針 |
37
- | -------------- | ------------------------ |
38
- | 要件詳細の補強 | 実案件適用時に具体化する |
42
+ ## 4. 入力
43
+
44
+ | 入力 | 入手元 | 利用目的 | 必須 | 正本 |
45
+ | ------------ | ------------------ | ------------------------------------------------ | ---- | ------------------ |
46
+ | 対象商品 | 商品台帳 | 販売状態、継続取扱、補充基準、発注単位を確認する | ○ | 商品台帳 |
47
+ | 現在庫 | 在庫記録 | 補充基準との差と補充必要数を確認する | ○ | 在庫記録 |
48
+ | 未完了依頼 | 補充依頼 | 同じ商品への重複依頼を防ぐ | ○ | 補充依頼 |
49
+ | 補充判断基準 | `br-reorder-point` | 補充要否と補充必要数を同じ規則で判定する | ○ | `br-reorder-point` |
50
+
51
+ 商品台帳、在庫記録、補充依頼は論理的な正本名であり、保存先や物理項目は本書では定めない。
52
+
53
+ ## 5. 処理
54
+
55
+ | ステップ ID | CDFD プロセス | 担当 | 入力 | 活動・判断 | 出力・完了条件 | 例外 |
56
+ | ----------- | ------------- | -------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | -------------- |
57
+ | `S-01` | `P-06` | 店主代表 | 対象商品、現在庫 | 販売状態、継続取扱、発注単位を確認し、補充判断の対象可否を決める | 補充判断の対象または補充不要のいずれかが理由付きで確定している | `E-01` |
58
+ | `S-02` | `P-06` | 店主代表 | 現在庫、補充基準、未完了依頼、発注単位 | `br-reorder-point` により補充要否と補充必要数を判定し、発注単位に合わせて依頼数量を算出する。未完了依頼との重複も確認する | 補充要否、依頼数量、重複有無を確認できる | `E-02`, `E-04` |
59
+ | `S-03` | `P-06` | 店主代表 | 補充要の判定結果 | 補充対象と依頼数量を確認し、判断根拠を添えて補充依頼を承認(確定)する | 商品、依頼数量、判断根拠、承認者、承認時刻を持つ補充依頼が確定している | `E-03` |
60
+ | `S-04` | `P-06` | 店主代表 | 確定した補充依頼 | 仕入グループへ確定した補充依頼を引き渡す(共有する) | 補充依頼が仕入グループへ引き渡され、参照可能な状態になる | `E-03` |
61
+
62
+ `S-01` または `S-02` で補充不要と判断した場合は `S-03` と `S-04` を起動せず、対象商品、判断根拠、確認時刻を補充不要記録として確定して終了する。
63
+
64
+ ## 6. 出力
65
+
66
+ | 出力 | 受け手 | 確定条件 | 正本 | 後続処理 |
67
+ | ------------ | ------------ | ---------------------------------------------------------------------- | -------- | ------------------------------ |
68
+ | 補充依頼 | 仕入グループ | 商品、依頼数量、判断根拠、店主代表の承認、承認時刻を確認できる | 補充依頼 | `P-01-01` 発注内容確定 |
69
+ | 補充不要記録 | 店主代表 | 対象商品、補充不要理由、確認時刻を確認でき、補充依頼が作成されていない | 在庫記録 | 次回の販売または入荷後に再判定 |
70
+
71
+ 補充依頼は `cdfd-uc-replenishment` の引き渡し `H-01` で仕入グループへ渡す情報に対応する。
72
+
73
+ ## 7. 例外・代替経路
74
+
75
+ | 例外 ID | 対象ステップ | 検出条件 | 停止範囲 | 担当 | 処置 | 再開条件・代替成果 |
76
+ | ------- | -------------- | ------------------------------------------------------------ | -------------------- | -------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------- |
77
+ | `E-01` | `S-01` | 商品、現在庫、補充基準、発注単位のいずれかが不明 | 補充要否の判定以降 | 店主代表 | 不足項目と対象商品を記録し、商品台帳または在庫記録の確認を依頼する | 不足項目が補完され、同じ発注単位で確認できた後に `S-01` から再開する |
78
+ | `E-02` | `S-02` | 同じ商品に未完了の補充依頼がある | 新しい補充依頼の確定 | 店主代表 | 既存依頼へ依頼数量を反映するか、新規依頼を作らないかを判断して記録する | 既存依頼を更新して再承認するか、重複不要の記録を代替成果として終了する |
79
+ | `E-03` | `S-03`、`S-04` | 判断根拠を記録できない、または仕入グループへ引き渡しできない | 補充依頼の引き渡し | 店主代表 | 補充依頼を非確定・未受領状態のまま保留し、状況を記録する | 判断根拠を確認するか引き渡し可能になった後に再開する |
80
+ | `E-04` | `S-02` | 未完了依頼を取得できない | 補充要否の判定以降 | 店主代表 | 処理を中断し、未完了依頼の取得失敗を記録する | 未完了依頼が取得可能になった後に `S-02` から再開する |
81
+
82
+ ## 8. 検証・受入観点
83
+
84
+ | 観点 | 入力条件 | 期待する業務成果 | 確認可能な記録 |
85
+ | -------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------- |
86
+ | 補充が必要 | 販売中の商品で、現在庫が補充基準を下回る | 店主代表が承認した補充依頼が一件確定し、仕入グループが商品と依頼数量を確認できる | 補充依頼、承認記録 |
87
+ | 補充が不要 | 現在庫が補充基準以上、または販売停止・終売である | 補充依頼を作らず、対象商品と補充不要理由が記録される | 在庫記録の補充不要記録 |
88
+ | 既存依頼と重複 | 同じ商品に未完了の補充依頼がある | 二重の補充依頼を作らず、既存依頼の更新または重複不要の判断を確認できる | 既存補充依頼、重複確認記録 |
89
+ | 重複確認不能 | 未完了依頼を取得できない状態である | 処理を中断し、二重の補充依頼を作らずに未完了依頼の取得失敗が記録される | 保留記録 |
90
+ | 判断情報が不足 | 商品、現在庫、補充基準、発注単位のいずれかが不明 | 補充依頼を確定せず、不足項目、確認担当、再開対象の商品が記録される | 保留記録 |
91
+ | 確定・引渡失敗 | 判断根拠が記録できない、または引き渡しできない状態である | 補充依頼を非確定・未受領状態のまま保留し、保留記録から状況を確認できる。再開後に承認・受領された補充依頼を確認できる | 保留記録、補充依頼 |
@@ -1,4 +1,4 @@
1
- # specdojo-schema: none reason=schema-not-defined
1
+ # yaml-language-server: $schema=../../../specdojo/schemas/v1/gl.schema.yaml
2
2
  id: specdojo:gl-sample
3
3
  title: "用語集: 在庫・調達"
4
4
  locale: ja
@@ -35,3 +35,19 @@ terms:
35
35
  definition: 駄菓子屋の店主。システムの主な利用者。
36
36
  notes: IT に詳しくない前提で画面を設計する。
37
37
  category: tm-actor
38
+
39
+ - id: tm-inventory
40
+ term: 在庫
41
+ definition: 管理対象の物品。
42
+
43
+ - id: tm-safety-stock
44
+ term: 安全在庫
45
+ definition: 需要変動に備えて保持する最小限の在庫量。
46
+
47
+ - id: tm-sales
48
+ term: 販売
49
+ definition: 商品を顧客に提供し、代金を受け取ること。
50
+
51
+ - id: tm-actor
52
+ term: アクター
53
+ definition: システムの利用者または外部システム。
@@ -0,0 +1,28 @@
1
+ # specdojo-schema: none reason=not-implemented
2
+
3
+ id: specdojo:ifx-index-sample
4
+ type: api
5
+ title: 外部システムIF一覧(main)
6
+ status: draft
7
+ supersedes: []
8
+
9
+ interfaces:
10
+ - name: 発注データ送信
11
+ source: 受発注管理(コンテナ)
12
+ target: 仕入先システム
13
+ direction: source_to_target
14
+ kind: ファイル
15
+ format: CSV
16
+ timing: 発注確定時
17
+ error_handling: 異常時は再送・管理者通知
18
+ spec_ref: ifx-file-orders
19
+
20
+ - name: 決済依頼/結果
21
+ source: 決済(コンテナ)
22
+ target: 決済サービス
23
+ direction: bidirectional
24
+ kind: API
25
+ format: JSON
26
+ timing: 決済時
27
+ error_handling: 失敗時はリトライ/保留
28
+ spec_ref: ifx-api-payment
@@ -11,12 +11,7 @@ based_on:
11
11
  version: 1
12
12
  project_id: prj-0001
13
13
 
14
- # 起動コマンドは .specdojo/exec-defaults.yaml の providers.<provider>.command_template
15
- # を member 属性で展開して解決するため、member には command を書かない。
16
- # この sample の custom provider は、次のテンプレートを定義している想定とする。
17
- # providers:
18
- # custom:
19
- # command_template: "specdojo-agent run --agent {nickname}"
14
+ # agent 定義は repository 共通の .specdojo/agent-members.yaml に置く。
20
15
 
21
16
  members:
22
17
  - nickname: po
@@ -35,69 +30,9 @@ members:
35
30
  scheduler_strategy: critical-first
36
31
  note: 人間の最終判断主体。小規模運用では管理と公開判断を兼務し、agent に承認責任を委ねない。
37
32
 
38
- - nickname: ba-edit-agent
39
- priority: 1
40
- display_name: Business Analyst Agent
41
- email: null
42
- roles:
43
- - BA
44
- type: agent
45
- provider: custom
46
- mode: edit
47
- proficiency: normal
48
- persona: requirements-navigator
49
- focus:
50
- - 販売、在庫、つけ管理の業務フロー整理
51
- - 利用者視点の受入条件確認
52
- - 要件の抜け漏れ確認
53
- capabilities:
54
- - web_search
55
- scheduler_strategy: dependency-first
56
- note: 要件整理と受入条件草案を支援する。最終判断は人間の PO が行う。
57
-
58
- - nickname: qe-review-agent
59
- priority: 1
60
- display_name: Quality Review Agent
61
- email: null
62
- roles:
63
- - QE
64
- type: agent
65
- provider: custom
66
- mode: review
67
- proficiency: normal
68
- persona: risk-averse-reviewer
69
- focus:
70
- - 受入条件の検証可能性確認
71
- - 欠品、会計ミス防止観点のレビュー
72
- - 禁止事項とルール準拠の確認
73
- capabilities:
74
- - web_search
75
- scheduler_strategy: fifo
76
- note: 品質観点のレビューを支援する。成果物の公開可否判断は行わない。
77
-
78
- - nickname: general-agent
79
- priority: 2
80
- display_name: General Support Agent
81
- email: null
82
- roles: []
83
- type: agent
84
- provider: custom
85
- mode: edit
86
- proficiency: low
87
- persona: general-assistant
88
- focus:
89
- - 草案作成支援
90
- - 表記ゆれ確認
91
- - 成果物間の軽微な整合性確認
92
- capabilities: []
93
- scheduler_strategy: manual
94
- note: 特定 Role に固定しない汎用支援 agent。実行時のタスク owner または plan で対象 Role を明示する。
95
-
96
33
  rules:
97
34
  - Schedule の owner には pm-roles.yaml に記載された Role code を使用し、member nickname は書かない。
98
35
  - specdojo exec --by には members[].nickname を指定し、実行ログ記録後の nickname は変更しない。
99
36
  - members[].roles は member が対応できる Role code を表し、Schedule の owner の代替として使わない。
100
- - agent は草案作成、レビュー支援、整合性確認、機械的更新を支援するが、最終承認、公開可否判断、説明責任は人間の PO が担う。
101
- - 起動コマンドは .specdojo/exec-defaults.yaml の providers.<provider>.command_template から解決する。member の command は、テンプレートを持たない構成に限って上書きとして使う。
102
- - command template と command 上書きには、認証情報、秘密鍵、トークン、個人環境に閉じたパスを記載しない。
37
+ - agent は .specdojo/agent-members.yaml に定義し、この名簿には記載しない。
103
38
  - 公開文書には個人名、私用メールアドレス、非公開組織情報を記載しない。
@@ -26,18 +26,19 @@ AI Agent は草案、整理、実装、検証を支援できるが、費用、
26
26
  ## 2. ロール・owner方針
27
27
 
28
28
  - 使用可能な Role code は `pm-roles.yaml` を正本とする。
29
- - 実行主体と兼務割り当ては `pm-members.yaml` を正本とする。
29
+ - 人間の実行主体と兼務割り当ては `pm-members.yaml`、agent は `.specdojo/agent-members.yaml` を正本とする。
30
30
  - Schedule の `owner` には Role code だけを使用し、個人名や agent 名は使用しない。
31
31
  - 小規模運用では1人が複数ロールを兼務できるが、判断責任と作業責任は RACI 上で区別する。
32
32
 
33
33
  ## 3. 正本と責任境界
34
34
 
35
- | 情報 | 正本 |
36
- | ---------------------- | ---------------------- |
37
- | Role code と責務 | `pm-roles.yaml` |
38
- | 実行主体と兼務 | `pm-members.yaml` |
39
- | 成果物・判断の責任 | `pm-raci.md` |
40
- | 関係者の関心・情報要求 | ステークホルダー登録簿 |
35
+ | 情報 | 正本 |
36
+ | ---------------------- | ------------------------------ |
37
+ | Role code と責務 | `pm-roles.yaml` |
38
+ | 人間の実行主体と兼務 | `pm-members.yaml` |
39
+ | agent の実行主体 | `.specdojo/agent-members.yaml` |
40
+ | 成果物・判断の責任 | `pm-raci.md` |
41
+ | 関係者の関心・情報要求 | ステークホルダー登録簿 |
41
42
 
42
43
  本書には人物一覧や詳細な RACI を複製しない。
43
44
 
@@ -48,7 +48,7 @@ specdojo:
48
48
  ## 4. Schedule・実行主体との対応
49
49
 
50
50
  - Schedule の `owner` は、その作業を主導する `R` の Role code と一致させる。
51
- - 実行主体と兼務は `pm-members.yaml` で管理し、本書へ個人名や agent 名を記載しない。
51
+ - 人間の実行主体と兼務は `pm-members.yaml`、agent は `.specdojo/agent-members.yaml` で管理し、本書へ個人名や agent 名を記載しない。
52
52
  - 成果物を統合・分割した場合も、各作業の `A` が不明にならないようにする。
53
53
  - 同じ実行主体が `A` と `R` を兼ねる場合も、判断と作業の証跡を分ける。
54
54
 
@@ -0,0 +1,40 @@
1
+ # yaml-language-server: $schema=../../../../docs/specdojo/schemas/v1/tml-index.schema.yaml
2
+
3
+ id: specdojo:tml-sample
4
+ type: project
5
+ status: draft
6
+ title: トラック順序計画
7
+ rulebook: specdojo:tml-rulebook
8
+ version: 1
9
+ project_id: prj-0001
10
+
11
+ tracks:
12
+ - track: launch
13
+ domains: [project-definition, project-management]
14
+ catalog_status: primary
15
+ order: 1
16
+ depends_on: []
17
+ note: プロジェクト全体の前提を定義する起点トラック。
18
+
19
+ - track: data-flow
20
+ domains: [data-flow]
21
+ catalog_status: primary
22
+ order: 2
23
+ parallel_group: business-specs
24
+ depends_on: [launch]
25
+
26
+ - track: data-model
27
+ domains: [data-model]
28
+ catalog_status: draft
29
+ catalog_duration_estimate_days: 3
30
+ order: 2
31
+ parallel_group: business-specs
32
+ depends_on: [launch]
33
+ note: data-flow と同じ入力を使うため並行候補とする。
34
+
35
+ - track: architecture
36
+ domains: [architecture]
37
+ catalog_status: not_started
38
+ catalog_duration_estimate_days: 2
39
+ order: 3
40
+ depends_on: [data-flow, data-model]
@@ -34,7 +34,7 @@ Markdown の Frontmatter と YAML・JSON の構造化メタデータに関する
34
34
  - SpecDojo が所有する項目はすべて `specdojo:` 名前空間(ネストしたオブジェクト)配下に置く。トップレベルは他フレームワーク(VitePress 等)の項目に明け渡し、SpecDojo は直接使わない。
35
35
  - `id` / `type` / `status` は全種別で必須とし、`specdojo:` 配下に置く。
36
36
  - `id` は共通スキーマの `idRef` に従い、`^[a-z0-9][a-z0-9-:]*$` に一致させる。
37
- - npm package が所有する実践体系文書の `id` は `<authority>:<local-id>` とし、SpecDojo core は `specdojo:` を使用する。これは Frontmatter の親キー `specdojo:` とは別に、ID値の所有元を表す namespace である。
37
+ - npm package が所有する型(Kata)の文書の `id` は `<authority>:<local-id>` とし、SpecDojo core は `specdojo:` を使用する。これは Frontmatter の親キー `specdojo:` とは別に、ID値の所有元を表す namespace である。
38
38
  - `type` は各ドキュメント種別のスキーマに定義された値を使用する。
39
39
  - `status` は `draft` / `ready` / `deprecated` のいずれかとする。
40
40
  - ドキュメント名は Frontmatter ではなく本文先頭の H1 に記述する。
@@ -253,27 +253,32 @@ specdojo:
253
253
 
254
254
  Markdown 文書の最新の継続品質評価は、プロジェクトの `<execution_path>/grade/results/<doc-id>.yaml` にサイドカーとして記録します。成果物の Frontmatter と本文には grade や finding を書き込みません。サイドカーは最新状態のスナップショットであり、`specdojo grade apply` は文書 ID ごとの同じファイルを冪等に上書きします。履歴は Job Run と evidence、合意形成は review result が担います。成果物の現在品質を参照するときは、サイドカーの `content_hash` が現在のファイル全体と一致することを確認します。
255
255
 
256
- | 項目 | 意味 |
257
- | ---------------- | ---------------------------------------------------------------------------- |
258
- | `rubric` | 判定に使った共通 rubric の版 |
259
- | `target` | `kata` または `deliverable` |
260
- | `verdict` | `pass` / `needs-work` / `fail` |
261
- | `score` | category の重み付き総合点(0-100) |
262
- | `graded_at/by` | 評価日時と `pm-members.yaml` の判定主体 nickname |
263
- | `content_hash` | 成果物ファイル全体の SHA-256 |
264
- | `categories` | category 別 score |
265
- | `viewpoints` | viewpoint 別 level / score |
266
- | `finding_counts` | `blocker` / `major` / `minor` / `note` の件数 |
267
- | `findings` | `id` / `severity` / `rule` / `line` / `anchor` / `message` の指摘一覧 |
268
- | `done_criteria` | 成果物カタログの完了条件の充足数・総数、未充足条件の担当 Role code、詳細参照 |
256
+ | 項目 | 意味 |
257
+ | ------------------- | ------------------------------------------------------------------------------------ |
258
+ | `rubric` | 判定に使った共通 rubric の版 |
259
+ | `target` | `kata` または `deliverable` |
260
+ | `verdict` | `pass` / `needs-work` / `fail` |
261
+ | `score` | category の重み付き総合点(0-100) |
262
+ | `graded_at/by` | 評価日時と人間・agent の合成名簿にある判定主体 nickname |
263
+ | `content_hash` | 成果物ファイル全体の SHA-256 |
264
+ | `categories` | category 別 score |
265
+ | `viewpoints` | viewpoint 別 level / score |
266
+ | `finding_counts` | `blocker` / `major` / `minor` / `note` の件数 |
267
+ | `findings` | `id` / `severity` / `rule` / `line` / `anchor` / `message` / `message_ja` の指摘一覧 |
268
+ | `level_corrections` | severity 上限に合わせて下方向へ補正した viewpoint と補正前後の level |
269
+ | `done_criteria` | 成果物カタログの完了条件の充足数・総数、未充足条件の担当 Role code、詳細参照 |
269
270
 
270
271
  `target: deliverable` で成果物カタログに `done_criteria` がある場合、サイドカーに要約を記録します。条件文、条件ごとの判定、不足理由は `<execution_path>/grade/criteria/` 配下の成果物ごとの YAML に記録し、`detail_ref` から参照します。同じ成果物の詳細ファイルは再評価ごとに上書きします。`satisfied` / `total` と総合 `score` / `verdict` は独立した評価軸であり、一方の値から他方を補完・上書きしません。
271
272
 
272
273
  未充足条件がある場合だけ `done_criteria.unsatisfied` を置き、条件 ID をキー、その条件の `roles` を値として記録します。これにより詳細を grade result へ複製せず、次の確認担当を特定できます。詳細 YAML は `grade-done-criteria.schema.yaml` に従い、成果物と同じ `content_hash` を持ちます。
273
274
 
274
- `findings[].line` は Frontmatter を除く本文での指摘行(1始まり)、`anchor` は評価時点の該当行の引用です。本文編集で行番号がずれた場合は `anchor` を照合に使います。`grade validate` はサイドカーの文書 ID・対象・件数・内容ハッシュを成果物と突き合わせます。
275
+ `findings[].line` は Frontmatter を除く本文での指摘行(1始まり)、`anchor` は評価時点の該当行の引用です。`message` は executor が出力した原文を正本として保存し、前回 finding の一致にも使います。`message_ja` は表示専用で、判定、score、severity、引き継ぎに使いません。旧サイドカーのように `message_ja` がない場合は `message` を表示します。本文編集で行番号がずれた場合は `anchor` を照合に使います。`grade validate` はサイドカーの文書 ID・対象・件数・内容ハッシュを成果物と突き合わせます。
275
276
 
276
- 再評価で同じ message の finding が残る場合は未解消として扱い、severity を前回より引き下げません。前回の問題が解消され、別の軽微な問題だけが残る場合は、新しい finding の message に severity を引き下げる根拠を含めます。
277
+ 再評価で正本の `message` が同じ finding が残る場合は未解消として扱い、severity を前回より引き下げません。`message_ja` の一致は使いません。日本語の `message` だけを持つ旧サイドカーはその日本語を互換用の正本として扱うため、英語へ翻訳した別文とは一致しません。前回の問題が解消され、別の軽微な問題だけが残る場合は、新しい finding の `message` に severity を引き下げる根拠を含めます。
278
+
279
+ executor は新しい判定根拠と finding を英語で出力します。機械変換後に `gemma26-translator` が英語 finding だけを日本語へ翻訳し、`message_ja` に保存します。モデルへ渡すのは英語文だけの配列であり、対応する index はコード側で管理します。`grade translation-plan` は元のインラインコードをそのまま残し、新しいインラインコードやバッククォートを加えず、固有名詞・識別子以外の英語の語句を日本語へ訳すよう求めます。`grade localize` は件数が一致するとき、各訳文が空でないこと、仮名を含むこと、元の文と訳文のインラインコードの多重集合が一致することを検証し、合格した項目だけを採用します。不合格項目は1件ずつ1回だけ再翻訳し、再び不合格なら `message_ja` に正本の `message` を保存します。件数が一致しない場合は全項目を不合格とします。executor が日本語で出力した finding は翻訳対象から外し、その原文を `message` と `message_ja` の両方に保存します。
280
+
281
+ 機械変換では、finding の severity が許す level 上限を超えた viewpoint だけを上限まで下げます。level を上げる補正や、viewpoint・severity・line の変更は行いません。補正した場合は `level_corrections` に viewpoint、`original_level`、`corrected_level` を保存します。
277
282
 
278
283
  サイドカーは `grade-result.schema.yaml` に従います。現在の評価対象は Markdown 文書であり、YAML / JSON を対象へ指定した場合はエラーとします。
279
284
 
@@ -46,7 +46,7 @@ repo/apps/product-b/docs/
46
46
 
47
47
  ドキュメントIDは、原則として **SpecDojo Unit 内で一意** にする。
48
48
 
49
- npm package が所有する実践体系は、利用プロジェクトの成果物と同じ Unit に展開しても所有元を識別できるよう、package ごとに定めた authority を ID の namespace として持つ。SpecDojo core の authority は `specdojo` とする。
49
+ npm package が所有する型(Kata)の文書は、利用プロジェクトの成果物と同じ Unit に展開しても所有元を識別できるよう、package ごとに定めた authority を ID の namespace として持つ。SpecDojo core の authority は `specdojo` とする。
50
50
 
51
51
  複数の SpecDojo Unit を横断して扱う場合は、必要に応じて Unit ID とドキュメントIDの組み合わせで識別する。
52
52
 
@@ -126,7 +126,7 @@ prj-0001:prj-charter
126
126
  prj-0001:sch-track-project-definition
127
127
  ```
128
128
 
129
- #### 3.1.3. 実践体系文書
129
+ #### 3.1.3. 型の文書
130
130
 
131
131
  npm package が所有する philosophy / standard / rulebook / recipe / sample / template / guide / reference は、authority を namespace として持つ。
132
132
 
@@ -198,7 +198,7 @@ prj-0002
198
198
 
199
199
  #### 3.2.3. namespace付きID
200
200
 
201
- プロジェクト文書とpackage所有の実践体系文書は、namespace と `local-id` をコロンで連結する。
201
+ プロジェクト文書とpackage所有の型の文書は、namespace と `local-id` をコロンで連結する。
202
202
 
203
203
  ```text
204
204
  <namespace>:<local-id>
@@ -220,7 +220,7 @@ id: "prj-0001:prj-overview"
220
220
  ### 3.3. ファイル名
221
221
 
222
222
  - 既定推奨は `ファイル名 = local-id`
223
- - プロジェクト文書でも実践体系文書でも、ファイル名には namespace を含めない
223
+ - プロジェクト文書でも型の文書でも、ファイル名には namespace を含めない
224
224
  - namespace はID上の論理的な所有元を表し、配置先ディレクトリと対応させる
225
225
 
226
226
  例:
@@ -265,11 +265,11 @@ specdojo:
265
265
 
266
266
  SpecDojo のドキュメントIDには、次の3種類がある。
267
267
 
268
- | 種類 | 形式 | 用途 |
269
- | ------------------- | ------------------------- | ------------------------------ |
270
- | ローカルID | `<local-id>` | プロダクト文書 |
271
- | プロジェクトID | `<project-id>:<local-id>` | プロジェクト文書 |
272
- | authority付き実践ID | `<authority>:<local-id>` | package が所有する実践体系文書 |
268
+ | 種類 | 形式 | 用途 |
269
+ | ------------------- | ------------------------- | -------------------------- |
270
+ | ローカルID | `<local-id>` | プロダクト文書 |
271
+ | プロジェクトID | `<project-id>:<local-id>` | プロジェクト文書 |
272
+ | authority付き実践ID | `<authority>:<local-id>` | package が所有する型の文書 |
273
273
 
274
274
  ### 4.2. プロダクト文書のID
275
275
 
@@ -318,9 +318,9 @@ prj-0001:prj-overview
318
318
  prj-0002:prj-overview
319
319
  ```
320
320
 
321
- ### 4.4. 実践体系文書のID
321
+ ### 4.4. 型の文書のID
322
322
 
323
- package が所有する実践体系文書は、package ごとに定めた authority を namespace として持つ。authority と local-id は英小文字、数字、ハイフンで構成し、`prj-` で始まる authority はプロジェクトIDとの混同を避けるため使用しない。
323
+ package が所有する型の文書は、package ごとに定めた authority を namespace として持つ。authority と local-id は英小文字、数字、ハイフンで構成し、`prj-` で始まる authority はプロジェクトIDとの混同を避けるため使用しない。
324
324
 
325
325
  ```text
326
326
  specdojo:<local-id>
@@ -427,7 +427,7 @@ IDには、次の情報を含めない。
427
427
  | 日付 | IDの永続性を損なうため。ただし議事録・進捗レポートなど時点そのものが識別子になる場合を除く |
428
428
  | ディレクトリ上の所属 | 配置ディレクトリが表すため。package の論理的な所有元は authority で表す |
429
429
 
430
- ### 4.10. 実践体系文書のlocal-id
430
+ ### 4.10. 型の文書のlocal-id
431
431
 
432
432
  `docs/ja/specdojo/` 配下のフレームワーク文書(guide、standard、reference、rulebook、recipe、sample、template)は、成果物文書の `<prefix>-<term>` とは逆に、主題語の後ろへ文書種別のサフィックスを置く。
433
433
 
@@ -463,7 +463,7 @@ specdojo-exec-operation-guide
463
463
 
464
464
  SpecDojo では、frontmatter の `id` には正規IDを使用する。
465
465
 
466
- 一方、参照フィールドでは、同一プロジェクト内に限りプロジェクト文書のローカル参照を許可する。package所有の実践体系文書は、所有元を曖昧にしないため常に authority 付き完全IDで参照する。
466
+ 一方、参照フィールドでは、同一プロジェクト内に限りプロジェクト文書のローカル参照を許可する。package所有の型の文書は、所有元を曖昧にしないため常に authority 付き完全IDで参照する。
467
467
 
468
468
  #### 5.1.1. 正規ID
469
469
 
@@ -789,7 +789,7 @@ specdojo deliverable trash --project prj-0001 --local-id cdfd-register-operation
789
789
  - 迷ったら「これは何についての文書か?」を名詞で考える
790
790
  - プロダクト文書はローカルIDを使う
791
791
  - プロジェクト文書は `<project-id>:<local-id>` を使う
792
- - package 所有の実践体系文書は `<authority>:<local-id>` を使い、SpecDojo core は `specdojo:` とする
792
+ - package 所有の型の文書は `<authority>:<local-id>` を使い、SpecDojo core は `specdojo:` とする
793
793
  - 同一プロジェクト内の参照では `<project-id>:` を省略してよい
794
794
  - 他プロジェクトへの参照では完全IDを使う
795
795
  - 入口は `-index`、横断定義は `-common` を使う
@@ -55,7 +55,7 @@ Job Definition Standard
55
55
  - `task.agent.executor` に、成果物の編集・検証・コマンド実行を担当する agent の nickname を書く。
56
56
  - result を executor が書かない構成(stage_role を持つ pipeline member)では、`task.agent.reporter` に reporter の nickname を書く。両方を指名した Run は executor → reporter の2段で実行され、result は reporter が書く。
57
57
  - `task.agent.reporter` を省略した場合、executor が Job Run の result まで記入する。result を書かない agent を単独で指名してはならない。
58
- - nickname は `pm-members.yaml` に登録済みの `type: agent` のメンバーと完全一致させる。`job validate` は書式のみを検査するため、実在確認は `exec run --job --dry-run` で行う。
58
+ - nickname は `.specdojo/agent-members.yaml` に登録済みのメンバーと完全一致させる。`job validate` は書式のみを検査するため、実在確認は `exec run --job --dry-run` で行う。
59
59
  - `exec run --by` は単一 agent 実行としての単発の差し替え、`--executor-by` / `--reporter-by` は段ごとの差し替えとして、いずれも Job の指名より優先する。
60
60
  - command Job で判断が必要な場合は `task.analysis.agent` に `stage_role: reporter` の nickname を指定する。`--reporter-by` で差し替えられるが、runner 実行を `--by` / `--executor-by` で agent に置き換えることはできない。
61
61
 
@@ -80,7 +80,17 @@ Job Definition Standard
80
80
  - Job は起動時刻を持たない。時刻条件は routine または外部スケジューラが持つ。
81
81
  - Job は agent 実行エンジンを持たない。plan 生成、agent 選択、result、worktree、commit は `exec` 実行基盤へ委ねる。
82
82
 
83
- ### 3.5. inputs と冪等性
83
+ ### 3.5. 統合前 review の宣言と review agent の規約
84
+
85
+ - Run の出力を統合前に review するかは Job の出力の性質で決まるため、Job の `task.review` で宣言する。routine の `action.commit` には書かない。
86
+ - `task.review` を持つ Job は、起動元(routine・手動の `exec run --job`)によらず、exec の worktree での実行、runner による commit、review、verdict による統合の流れで動く。Job は宣言だけを持ち、worktree・commit・review・統合は `exec` 実行基盤が担う。
87
+ - `task.review` は `edit` / `review` / `command` のいずれの mode でも書ける。空の mapping(`review: {}`)は、review agent を指名せずに宣言だけを行う。
88
+ - review agent は `task.review.agent.executor`(review executor)と `task.review.agent.reporter`(reporter)に nickname で指名する。書式と未知のキーの扱いは `task.agent` と同じで、`executor` は必須、`reporter` は任意、それ以外のキーは `job validate` がエラーにする。
89
+ - review agent の解決順は、`exec run` の `--review-by` / `--reporter-by` → `task.review.agent` → 自動選択とする。review タスクは能力要件を持たないため、自動選択では利用者の意図した agent にならない場合がある。review の品質を固定したい Job は指名する。
90
+ - `task.review.agent` は Job Run 自体の agent(`task.agent` / `task.analysis.agent`)とは独立している。`--reporter-by` は従来どおり Run の reporter と review の reporter の両方を差し替える。
91
+ - routine の `action.commit: true` は互換として読み、`task.review` を宣言していない Job でも同じ流れで実行する。Job が `task.review` を宣言している場合は Job を優先し、`action.commit` の有無や値によらず review を経て統合する。
92
+
93
+ ### 3.6. inputs と冪等性
84
94
 
85
95
  - `inputs` には、実行内容または表示内容を決める値(期間、対象種別、上限件数)だけを置く。
86
96
  - string / integer / boolean は `enum` で許容値を、list は `enum` で各要素の許容値を制限できる。integer の範囲は `minimum` / `maximum` で制限する。既定値にも同じ制約を適用する。
@@ -92,23 +102,27 @@ Job Definition Standard
92
102
 
93
103
  ## 4. 値制約・判定基準
94
104
 
95
- | 項目 | 必須 | 判定基準 |
96
- | ---------------------- | ---- | ------------------------------------------------------------------ |
97
- | `id` | ○ | `job-<slug>` 形式で、ファイル名の拡張子を除いた部分と一致する |
98
- | `task.mode` | ○ | `edit` / `review` / `command` |
99
- | `task.description` | 条件 | `edit` / `review` で必須。決定論的手順の列挙を含まない |
100
- | `task.command` | 条件 | `command` で必須。入力展開後も非空 |
101
- | `task.precondition` | 任意 | `command` と `empty-output` または 0〜255 の終了コードを指定 |
102
- | `task.analysis` | 任意 | command 結果の判断が必要な場合だけ agent と description を指定 |
103
- | `task.targets` `paths` | 条件 | `edit` / `review` はいずれか必須。`command` では任意 |
104
- | `task.agent.executor` | 任意 | `pm-members.yaml` の nickname 書式(`^[a-z0-9][a-z0-9_-]{0,62}$`) |
105
- | `task.agent.reporter` | 任意 | 同上。executor が result を書かない構成では必須 |
106
- | `inputs.*.enum` | 任意 | scalar の値または list の各要素に対する非空の許容値集合 |
107
- | `minimum` / `maximum` | 任意 | integer input だけに指定でき、`minimum <= maximum` |
108
- | `run.idempotency_key` | ○ | 空文字へ解決されず、同じ論理実行を一意に判別できる |
105
+ | 項目 | 必須 | 判定基準 |
106
+ | ---------------------- | ---- | ------------------------------------------------------------------------------- |
107
+ | `id` | ○ | `job-<slug>` 形式で、ファイル名の拡張子を除いた部分と一致する |
108
+ | `task.mode` | ○ | `edit` / `review` / `command` |
109
+ | `task.description` | 条件 | `edit` / `review` で必須。決定論的手順の列挙を含まない |
110
+ | `task.command` | 条件 | `command` で必須。入力展開後も非空 |
111
+ | `task.precondition` | 任意 | `command` と `empty-output` または 0〜255 の終了コードを指定 |
112
+ | `task.analysis` | 任意 | command 結果の判断が必要な場合だけ agent と description を指定 |
113
+ | `task.targets` `paths` | 条件 | `edit` / `review` はいずれか必須。`command` では任意 |
114
+ | `task.agent.executor` | 任意 | `.specdojo/agent-members.yaml` の nickname 書式(`^[a-z0-9][a-z0-9_-]{0,62}$`) |
115
+ | `task.agent.reporter` | 任意 | 同上。executor が result を書かない構成では必須 |
116
+ | `task.review` | 任意 | mapping。存在すれば統合前 review の宣言。`agent` 以外のキーを持たない |
117
+ | `task.review.agent` | 任意 | `executor` 必須・`reporter` 任意。書式は `task.agent` と同じ nickname 書式 |
118
+ | `inputs.*.enum` | 任意 | scalar の値または list の各要素に対する非空の許容値集合 |
119
+ | `minimum` / `maximum` | 任意 | integer input だけに指定でき、`minimum <= maximum` |
120
+ | `run.idempotency_key` | ○ | 空文字へ解決されず、同じ論理実行を一意に判別できる |
109
121
 
110
122
  ## 5. 記述例
111
123
 
124
+ 次の grade Job は SpecDojo 本体リポジトリを保守するための例です。`tools/grade/run-per-document.sh` は本体リポジトリの開発用で npm package には含まれません。v0.3.0 の公開物における grade は試験的で、利用者は `grade list` / `plan` / `apply` / `validate` / `result` などの部品を組み合わせます。成果物の grade には project の `catalog_path` が必要です。
125
+
112
126
  ```yaml
113
127
  task:
114
128
  mode: command
@@ -126,10 +140,16 @@ task:
126
140
  閾値の見直し要否を判断して報告する。
127
141
  paths:
128
142
  - docs/ja/specdojo/rulebooks
143
+ review:
144
+ agent:
145
+ executor: claude-expert-review-executor
146
+ reporter: claude-reporter
129
147
  run:
130
148
  idempotency_key: "{{job_id}}:{{scheduled_at}}"
131
149
  ```
132
150
 
151
+ この例は `task.review` で統合前 review を宣言し、review agent を指名しています。routine から起動しても手動で `exec run --job` を実行しても、Run の出力は worktree で commit され、`claude-expert-review-executor` と `claude-reporter` の review を経て、verdict が `complete` / `complete-with-findings` の場合だけ統合されます。
152
+
133
153
  ## 6. 禁止事項
134
154
 
135
155
  - 対象文書の列挙、段の順序制御、1件ごとの CLI 実行を `task.description` へ書かない。自然言語で書かれた script は Job の責務ではない。
@@ -142,7 +162,7 @@ run:
142
162
  ## 7. 運用・見直しルール
143
163
 
144
164
  - `job-*.yaml` を変更した場合は `specdojo job validate --project <project-id>` を実行する。
145
- - agent の指名を変更した場合は `specdojo exec run --job <job-id> --dry-run` で、解決された nickname とコマンドを確認する。
165
+ - agent の指名を変更した場合は `specdojo exec run --job <job-id> --dry-run` で、解決された nickname とコマンドを確認する。`task.review` を宣言した Job では、同じ dry-run が review executor / reporter の nickname と解決元(`--review-by` / `--reporter-by`・`task.review.agent.*`・`auto`)を表示する。
146
166
  - Job を統廃合した場合は、参照する routine の `action` と運用ガイドの記述を同じ変更で更新する。
147
167
  - script または CLI へ手順を移した場合は、移し先の入口と引数を `command-reference` に記載し、Job からはその入口だけを呼ぶ。
148
168
  - `task.precondition` を追加・変更した場合は、選択 0 件の skip と 1 件以上の通常 materialize の両方をテストする。